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About This Manual 


This manual contains information needed by systems engineers who write device 

drivers for the ULTRIX SCSI/CAM Architecture interfaces. 

Audience 

This manual is intended for systems engineers who: 

• Develop programs in the C language using standard library routines 

• Know one or more UNIX shells, other than csh 

• Understand basic ULTRIX components such as the kernel, shells, processes, 
configuration, autoconfiguration, and so forth 

• Understand how to use the ULTRIX programming tools, compilers, and 
debuggers 

• Develop programs in an environment that includes dynamic memory allocation, 
linked list data structures, multitasking and symmetric multiprocessing (SMP) 

• Understand the hardware device for which the driver is being written 


Organization 

This manual is organized as follows: 

Chapter 1 ULTRIX SCSI/CAM Software Architecture 

Presents an overview of the ULTRIX SCSI CAM Architecture 
(USCA). 

Chapter 2 CAM User Agent Modules 

Describes the User Agent routines provided by Digital for SCSI/CAM 
peripheral device driver writers 

Chapter 3 USCA Common Modules 

Describes the common data structures, routines, and macros provided 
by Digital for SCSI/CAM peripheral device driver writers 

Chapter 4 USCA Generic Modules 

Describes the generic routines provided by Digital for SCSI/CAM 
peripheral device driver writers 

Chapter 5 CAM Data Structures 

Describes members of the CAM data structures used by SCSI device 
drivers. 

Chapter 6 SCSI/CAM Configuration Driver Modules 

Describes the CAM Configuration driver data structures and routines 
that call the initialization routines in all the CAM subsystem modules. 

CAM XPT I/O Support Routines 


Chapter 7 





Discusses the Transport (XPT) layer routines used with SCSI device 
drivers. 

Chapter 8 

CAM SIM Modules 

Discusses the data structures and routines used with the SCSI 

Interface Module (SIM) layers that interface with the CAM 
subsystem. 

Chapter 9 

USCA Error Handling 

Discusses the macro, data structures, and routines supplied by Digital 
for error handling in SCSI/CAM device drivers. 

Chapter 10 

USCA Debugging Facilities 

Describes the debugging routines supplied by Digital for SCSI/CAM 
peripheral device driver writers. 

Chapter 11 

Programmer-Defined SCSI/CAM Device Drivers 

Describes how programmers can define SCSI/CAM device drivers, 
with examples. 

Chapter 12 

SCSI/CAM Special I/O Interface 

Describes the SCSI/CAM special I/O interface supplied by Digital to 
process special SCSI I/O commands, with examples. 

Appendix A 

Header Files Used by SCSI/CAM Device Drivers 

Summarizes the header files used by SCSI/CAM device drivers. 

Appendix B 

Summary of Device Driver Routines 

Summarizes the general device driver routines used by SCSI/CAM 
device drivers. 

Appendix C 

SCSI/CAM Routines in ULTRIX Reference Page Format 

Provides more detailed descriptions of the USCA routines in ULTRIX 
reference page format. 


Related Documentation 

Readers of this guide are assumed to be familiar with the following documents: 

• American National Standard for Information Systems, SCSI-2 Common Access 
Method: Transport and SCSI Interface Module , working draft, X3T9.2/90-186 
Terms used in this guide, such as CAM Control Block (CCB), are defined in that 
document. Copies may be purchased from Global Engineering, 2805 McGaw St, 
Irvine, CA 92714, telephone 800-854-7179. 

• American National Standard for Information Systems, Small Computer Systems 
Interface - 2 (SCSI - 2), X3T9/89-042 

The following documents contain information that pertains to writing device drivers: 

• Guide to Writing and Porting VMEbus and TURBOchannel Device Drivers 
This guide contains information needed by systems engineers who write and port 
device drivers for the VMEbus and the TURBOchannel. Systems engineers who 
write drivers that operate on other buses can find information on driver concepts, 
interfaces to device driver routines, kernel structures, kernel routines used by 
device drivers, installation of device drivers, and header files related to device 
drivers. 

• Guide to Configuration File Maintenance 

This guide contains information on how to maintain the system configuration file 
and how to build a new kernel, either automatically or manually. The 
configuration file provides you with the ability to configure your system to meet 
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your needs. You should read this manual if you are responsible for maintaining 
an ULTRIX system. You should also read parts of this manual if you are 
planning to modify or write device drivers. 

• Guide to the Error Logger 

This guide contains information about the error logger and how it records and 
reports errors and other events that occur on your ULTRIX system. The guide 
gives an overview of the error logger, describes how to control error logger 
functions, and describes using the Error Report Formatter, uerf. You should 
read this manual if you manage error information on an ULTRIX system. 


Conventions 


% 


% cat 


filename 

cat file 
cat(l) 


The default user prompt is your system name followed by a right 
angle bracket. In this manual, a percent sign (%) is used to represent 
this prompt. 

A regular constant-width typeface is used for code examples, system 
prompts in interactive examples, and names of commands and other 
literal strings in text. A bold constant-width typeface is used for 
typed user input in interactive examples and for routines in function 
definitions. 

In examples, syntax descriptions, and function definitions, this 
typeface indicates variable values. 

In syntax definitions, a bold sans serif typeface is used for literal 
strings and a sloping sans serif typeface is used for variable values. 

A cross-reference to a reference page include the appropriate section 
number in parentheses. For example, a reference to cat(l) indicates 
that you can find the material on the cat command in Section 1 of 
the reference pages. 
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ULTRIX SCSI/CAM Software Architecture 


1 


This chapter provides an overview of the ULTRIX Small Computer System Interface 
(SCSI) Common Access Method (CAM) Architecture (USCA). which is a reliable, 
maintainable, and high performance SCSI subsystem based on the industry-standard 
CAM architecture. Readers of this guide should be familiar with the following 
documents: 

• American National Standard for Information Systems, SCSI-2 Common Access 
Method: Transport and SCSI Interface Module, working draft, X3T9.2/90-186 

Terms used in this guide, such as CAM Control Block (CCB), are defined in that 
document. Copies may be purchased from Global Engineering, 2805 McGaw St, 
Irvine, CA 92714, telephone 800-854-7179. 

• American National Standard for Information Systems, Small Computer Systems 
Interface - 2 (SCSI - 2), X3T9/89-042 

This chapter describes the following: 

• The CAM and USCA environment models 

• The User Agent driver 

• The SCSI/CAM peripheral device driver routines 

- The CAM common routines supplied by Digital 

- The generic routines supplied by Digital 

- The SCSI disk device routines 

- The SCSI tape device routines 

- The SCSI CDROM/AUDIO device commands 

- The SCSI/CAM Special I/O interface 

• The CAM Configuration driver 

• The CAM Transport layer 

• The SCSI Interface Module (SIM) 


1.1 Overview 

The CAM architecture defines a software model that is layered, providing hardware 
independence for SCSI device drivers and SCSI system software. In the CAM 
model, which is illustrated in Figure 1-1, a single SCSI/CAM peripheral driver 
controls SCSI devices of the same type, for example, direct access devices. This 
driver communicates with a device on the bus through a defined interface. Using this 
interface makes a SCSI/CAM peripheral device driver independent of the underlying 
SCSI Host Bus Adapter (HBA). 




This hardware independence is achieved by using the Transport (XPT) and SCSI 
Interface Module (SIM) components of CAM. Because the XPT/SIM interface is 
defined and standardized, users and third parties can write SCSI/CAM peripheral 
device drivers for a variety of devices and use existing operating system support for 
SCSI. The drivers do not contain SCSI HBA dependencies; therefore, they can run 
on any hardware platform that has an XPT/SIM interface present. 


Figure 1-1: CAM Environment Model 
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Figure 1-2 illustrates the ULTRIX SCSI/CAM implementation of that model. 
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Figure 1-2: ULTRIX SCSi/CAM Architecture Implementation Model 




Transport Layer - XPT 




ZK-0252U-R 


CAM User Agent Device Driver 

The User Agent driver lets user process CAM Control Block (CCB) requests to the 
XPT pass through for processing. The CCB contains all information required to 
fulfill the request. The user process calls the User Agent indirectly, using the 
ioctl(2) system call. A new User Agent CCB is allocated by a call to the XPT 
layer, and the user-process CCB information is copied into kernel space. The new 
CCB is filled in with the CCB values from the user process. If necessary, the user 
data areas are locked in memory. The CCB is then sent to the CAM subsystem for 
processing. 

Once the request has completed, the User Agent driver’s completion routine is called. 
That routine performs all necessary cleanup operations and notifies the user process 
that the request is complete. 

The User Agent allows multiple processes to issue CCBs, so there may be multiple 
processes sleeping on the User Agent. All CCBs are queued at the SIM layer. 
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1.3 SCSI/CAM Peripheral Device Drivers 

SCSI/CAM peripheral device drivers convert operating system requests, such as user 
process reads or writes, into CAM requests that the SCSI/CAM subsystem can 
process. Each type of SCSI/CAM peripheral driver is responsible for a specific class 
of SCSI device, such as SCSI tape devices. The SCSI/CAM peripheral driver 
handles error codes and conditions for its SCSI device class. 

SCSI/CAM peripheral drivers convert input/output (I/O) requests into CAM Control 
Blocks (CCBs) that contain SCSI Command Descriptor Blocks (CDBs). CCBs are 
presented to the underlying transport layer, XPT, to initiate I/O requests. SCSI/CAM 
peripheral drivers implement SCSI device error recovery, for example, dynamic bad 
block replacement (DBBR). The SCSI device driver has no access to SCSI device 
control and status registers (CSRs) and receives no SCSI device interrupts. 

The major/minor device-number pair, which is 16 bits wide, is used as an argument 
when creating the device special file associated with a specific SCSI device and is 
contained in the buf structure when accessing the device in raw or blocked mode. 
The 16 bits are allocated as follows: 


15_1211 10 9 7 6 4 3 0 


Major Index 

Bus# 

Target ID 

LUN 

Device Specific 
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The major number range goes from HEX 60 to HEX 6f and the minor number range 
goes from HEX 00 to HEX fO. For example, a device that starts with a major 
number of 0x60 and a minor number of 0x00 represents Bus 0, Target 0, and 
Logical Unit 0. The last SCSI device that this sample device driver would control 
has major number 0x6f and minor number OxfO. This represents Bus 4, Target 7, and 
Logical Unit 7. 

This section provides overviews of the following: 

• Common SCSI device driver modules 

• Generic SCSI device driver modules 

• SCSI disk device driver modules 

• SCSI tape device driver modules 

• SCSI CDROM/AUDIO device driver modules 

Chapters 3, 4, and 11 describe the data structures and the routines associated with 
each module. 


1.3.1 USCA Common Device Driver Modules 

The common SCSI device driver structures and routines can be shared among all the 
SCSI/CAM peripheral drivers written by device driver writers for ULTRIX. Using 
these common routines can speed the process of writing a SCSI device driver by 
providing routines that any SCSI device driver can use to perform operations. 
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1.3.2 USCA Generic Device Driver Modules 

Digital supplies predefined data structures and formats that SCSI device driver 
writers can use to write generic SCSI/CAM peripheral device drivers. These data 
structures and formats can be used in conjunction with the common routines. 

Chapter 4 includes a sample generic SCSI device driver using the common routines. 

1.3.3 CAM SCSI Disk Device Driver Modules 

The SCSI/CAM peripheral disk driver supports removable (floppy) and 
nonremovable direct access SCSI disk devices and CDROM devices. The user 
interface consists of the major/minor device number pair and the ioctl commands 
supported by the SCSI disk device driver. The SCSI disk device driver also uses the 
common routines. 

1.3.4 CAM SCSI Tape Device Driver Modules 

The SCSI tape device structures and routines are exclusive to the SCSI/CAM 
peripheral tape driver. The user interface consists of the major/minor device number 
pair and the ioctl commands supported by the SCSI tape device driver. The SCSI 
tape device driver also uses the common routines. 

1.3.5 CAM SCSI CDROM/AUDIO Device Driver Modules 

The SCSI CDROM/AUDIO device commands, which are described in Chapter 11, 
use the SCSI CDROM/AUDIO device structures. The SCSI CDROM/AUDIO 
device driver also uses the common routines. 


1.4 SCSI/CAM Special I/O Interface 

The USCA software includes an interface developed to process special SCSI I/O 
control commands used by the existing Digital SCSI subsystem and to aid in porting 
new or existing SCSI device drivers from other vendors to the USCA. With the 
SCSI/CAM special I/O interface, SCSI/CAM peripheral driver writers do not need 
detailed knowledge of either the system-specific or the CAM-specific structures and 
routines used to issue a SCSI command to the CAM I/O subsystem. 


1.5 The SCSI/CAM Configuration Driver 

The Configuration driver is responsible for configuring and initializing the CAM 
subsystem. This driver is also responsible for maintaining the cam_edt [ ] 
information structure. 

When the system powers up, the Configuration driver initializes the local and global 
CAM subsystem data structures. The Configuration driver also calls the XPT and 
SIM initialization routines. Once the subsystems are initialized, the Configuration 
driver performs a SCSI-bus scan by sending the SCSI Device Inquiry command. The 
cam_edt [ ] structure contains the returned SCSI inquiry data for the SCSI/CAM 
peripheral drivers to access. The drivers, using the XPT_GDEV_TYPE and 
XPT_SDEV_TYPE get and set device information CCBs, can access the data 
contained in cam_edt [ ]. 
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1.6 CAM Transport Layer (XPT) 

The CAM transport layer, XPT, handles the CAM requests from the SCSI/CAM 
peripheral drivers and routes them to the appropriate SIM module. The XPT provides 
routines which are called by the SCSI/CAM peripheral driver to allocate and 
deallocate CAM control blocks (CCBs). In addition, the XPT provides routines that 
are used to initiate requests to the SIM and to issue asychronous callbacks. 


1.7 SCSI Interface Module Layers (SIM) 

The SCSI Interface Module, SIM, has the most interaction with the SCSI bus 
protocol, timings, and other hardware-specific operations. Although this is a single 
component in the CAM model, it is divided into four logical sublayers in ULTRIX: 

• SIM XPT - The SIM layer that interfaces to the XPT to initiate I/O on behalf of 
the SCSI/CAM peripheral drivers. 

• SIM SCHEDULER - The SIM layer that schedules requests to the SIM HBAs. 

• SIM HBA - The SIM layer that contains the HBA device-specific information. 

• SIM DME - A low level layer that contains the architecture-specific data- 
movement code. 
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This chapter describes the functions of the ULTRIX User Agent SCSI device driver. 
It also describes the User Agent data structures and routines used by the User Agent 
SCSI device driver. 


2.1 User Agent Introduction 

The ULTRIX User Agent SCSI device driver lets device driver writers write an 
application program to build a CAM Control Block (CCB) request. The User Agent 
driver lets the user-process request pass through to the XPT layer for processing. 

This gives user processes access to the SCSI/CAM subsystem and to all types of 
SCSI/CAM peripheral devices attached to the system. 

This is a simple method for passing the CCB’s SCSI request to the devices using the 
SIMs. The kernel does not have to be rebuilt if the device driver writer wants to 
change values within the CCBs. 

The CCB contains all the information required to perform the request. The user 
process calls the User Agent SCSI device driver using the ioctl system call. See 
ioctl(2) for more information. The User Agent ioctl routine, uagt_ioctl, is 
called through the device switch table, which is indexed by the major device number 
of the User Agent driver specified in the ioctl call. The ioctl commands 
supported by the User Agent SCSI device driver are: DEVIOCGET, which returns 
the SCSI device driver status; UAGT_CAM_IO, which sends the specified CCB to 
the XPT layer for processing; UAGT_CAM_SINGLE_SCAN, which causes the scan 
of a bus, target, and LUN; and UAGT_CAM_FULL_SCAN, which causes the scan 
of a bus. 

A CCB is allocated in the kernel and the user process’s CCB is copied to the kernel 
CCB. The User Agent SCSI device driver sleeps waiting for the request to complete; 
then, all necessary cleanup is performed, and the user process is notified of the 
completion of the request. If a signal is caught, an ABORT CCB is issued to try to 
terminate the outstanding CCB for the user process. 

The User Agent SCSI device driver allows multiple processes access to the XPT 
layer; therefore, there may be multiple processes sleeping on the User Agent. All 
CCBs passed through by the User Agent are queued at the SIM layer. 


2.2 User Agent Error Handling 

The User Agent SCSI device driver performs limited error checking on the CCB 
pointed to in the UAGT_CAM_CCB structure passed from the user process. The 
User Agent driver verifies that the uagt_ccblen is not greater than the maximum 
length for a CCB, checks that the XPT function code is valid, and checks that the 
Target ID and LUN specified are within the range allowed. The User Agent does not 
issue a REQUEST SENSE command in response to a CHECK CONDITION status. 
Autosensing is assumed to be enabled. The application program is responsible for 




issuing a RELEASE SIM QUEUE CCB. 

The following error codes are returned by the User Agent: 

• EFAULT - An error occurred in copying to or from user space. 

• EBUSY - Out of resources (the User Agent request table is full). 

• EINVAL - An invalid target or LUN was passed to the User Agent driver, or the 
CCB copied from the user process contained an invalid parameter. 

2.3 User Agent Data Structures 

This section describes the data structures the User Agent uses. 

2.3.1 The UAGT_CAM_CCB Data Structure 

The User Agent SCSI device driver uses the UAGT_CAM_CCB data structure to 
communicate with the user processes requesting access to the SCSI/CAM subsystem. 

The user process fills in the pointers in the UAGT_CAM_CCB data structure. The 
structure is copied into kernel space. The user process’s CCB is copied into kernel 
space by the User Agent. 

If necessary, the user data area and the sense data area are locked in memory. If the 
pointers are not needed with the requested CCB, the pointers must be set to NULL. 

The CCB contains all the information necessary to execute the requested XPT 
function. The addresses in the CCB are used by the SIM and must be valid. The 
User Agent will not modify the corresponding pointers in the CCB. 

The CCB definition is different for each of the following XPT functions supported by 
the User Agent SCSI device driver: 

• XPT_NOOP - Execute nothing. 

• XPT_SCSI_IO - Execute the requested SCSI 10. 

• XPT_GDEV_TYPE - Get the device type information. 

• XPT_PATH_INQ - Path inquiry. 

• XPT_REL_SIMQ - Release the SIM queue that was frozen by a previous 
CHECK CONDITION status. 

• XPT_SASYNC_CB - Set async callback parameters. 

• XPT_SDEV_TYPE - Set the device type information. 

• XPT_ABORT - Abort the selected CCB. 

• XPT.RESETJBUS - Reset the SCSI bus. 

• XPT_RESET_DEV - Reset the SCSI device, BDR. 

• XPT_TERM_IO - Terminate the selected CCB. 

If a signal is generated by the user process, the User Agent creates an XPT_ABORT 
CCB to abort the outstanding I/O and then waits for the completion of the I/O and 
notifies the user process when the aborted CCB is returned to the User Agent. 
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The UAGT_CAM_CCB structure is defined as follows: 

typedef struct uagt_cam_ccb 
{ 

CCB_HEADER *uagt_ccb; 
u_long uagt_ccblen; 
u_char *uagt_buffer; 
u_long uagt_buflen; 
u_char *uagt_snsbuf; 
u_long uagt_snslen; 

CDB_UN *uagt_cdb; 
u_long uagt__cdblen; 
ulong uagt_flags; 

] UAGT_CAM_CCB; 

2.3.1.1 The uagt_ccb Member 

The uagt_ccb member contains a pointer to the user process’s CCB that will be 
copied into kernel space- 

2.3.1.2 The uagt_ccblen Member 

The uagt_ccblen member contains the length of the user process’s CCB. 

2.3.1.3 The uagt_buffer Member 

The uagt_buf f er member contains a pointer to the user process’s data buffer. 

This member is used only by the User Agent. 

2.3.1.4 The uagt.buflen Member 

The uagt_buf len member contains the length of the user process’s data buffer. 
This member is used only by the User Agent. 

2.3.1.5 The uagt_snsbuf Member 

The uagt_snsbuf member contains a pointer to the user process’s autosense data 
buffer. This member is used only by the User Agent. 

2.3.1.6 The uagt_snslen Member 

The uagt snslen member contains the length of the user process’s autosense data 
buffer. This member is used only by the User Agent. 

2.3.1.7 The uagt_cdb Member 

If the user process’s CCB contains a pointer to a CDB, then the uagt cdb also 
contains a pointer to a Command Descriptor Block (CDB) that is to be locked in 
memory. This member and the uagt_cdblen member are used only by the User 
Agent driver. The CCB must also contain valid pointers and counts. 

2.3.1.8 The uagt_cdblen Member 

The uagt_cdblen contains the length of the Command Descriptor Block, if 
appropriate. 


/* pointer to the users CCB */ 

/* length of the users CCB */ 

/* pointer for the data buffer */ 

/* length of user request */ 

/* pointer for the sense buffer */ 
/* length of user's sense buffer */ 
/* ptr for a CDB if not in CCB */ 

/* CDB length if appropriate */ 

/* See below */ 
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2.3.1.9 The uagt_flags Member 

The uagt_f lags contains the UAGT_NO_INT_SLEEP bit, which, if set, indicates 
that the User Agent should not sleep at an interruptible priority. 

2.3.2 The UAGT.CAM.SCAN Data Structure 

The User Agent SCSI device driver uses the UAGT_CAM_SCAN data structure to 
communicate with user level programs that need to have access to the CAM 
subsystem. The structure is copied into kernel space as part of the ioctl system 
call from user space for the UAGT_CAM_SINGLE_SCAN and 
UAGT_CAM_FULL_SCAN commands. The user program fills in the pointers in 
this structure and the User Agent SCSI device driver correctly fills in the 
corresponding pointers in the CCB. 

The UAGT_CAM_SCAN structure is defined as follows: 

typedef struct uagt_cam_scan { 


u_ 

char 

ucs_bus; 

/* 

Bus id for scan */ 

u_ 

char 

ucs_target; 

/* 

Target id for scan */ 

u_ 

char 

ucs_lun; 

/* 

LUN for scan */ 


} UAGT_CAM_SCAN; 


2.4 User Agent Routines 

This section describes the User Agent routines supplied by Digital. Table 2-1 lists 
the name of each routine and gives a summary description of its function. The 
sections that follow contain a more detailed description of each User Agent routine. 
Descriptions of the routines with syntax information, in ULTRIX reference page 
format, are included in alphabetical order in Appendix C. 


Table 2-1: User Agent Routines 


Routine 

Summary Description 

uagt_open 

uagt_close 

uagt__ioctl 

handles the open of the User Agent driver 
handles the close of the User Agent driver 
handles the ioctl system call for the User Agent driver 


2.4.1 The uagt_open Routine 

The uagt open routine handles the open of the User Agent driver. 

The character device special file name used for the open is /dev/cam. 

2.4.2 The uagt_close Routine 

The uagt_close routine handles the close of the User Agent driver. For the last 
close operation for the driver, if any queues are frozen, a RELEASE SIM QUEUE 
CCB is sent to the XPT layer for each frozen queue detected by the User Agent. 
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2.4.3 The uagtjoctl Routine 

The uagt_ioctl routine handles the ioctl system call for the User Agent driver. 
The ioctl commands supported are: DEVIOCGET, to obtain the User Agent 
driver’s SCSI device status; UAGT_CAM_IO, the ioctl define for calls to the User 
Agent driver; UAGT_CAM_SINGLE_SCAN, to scan a bus, target, and LUN; and 
UAGT_CAM_FULL_SCAN, to scan a bus. 

For SCSI I/O CCB requests, the user data area is locked before passing the CCB to 
the XPT. The User Agent sleeps waiting for the I/O to complete and issues a 
ABORT CCB if a signal is caught while sleeping. 


2.5 Sample User Agent Drivers 

Two sample User Agent driver programs follow. The first sample program uses the 
User Agent driver to perform a SCSI INQUIRY command to a device on a selected 
nexus. 

The second sample program is a scanner control program that sets up a scanner, reads 
scan line data from the device, and writes the data to a file, using the User Agent 
driver. 

Both programs are included with the USCA software and reside in the 
/usr/examples directory. 


2.5.1 Sample User Agent Driver Inquiry Program 

This section contains the User Agent sample inquiry application program, 
caminq. c, with annotations to the code. The user enters the string inq followed 
by the numbers identifying the bus, target, and LUN nexus to be checked for a valid 
device. If the device is valid, the INQUIRY data is displayed at the console. If the 
device is invalid, an error message appears. 


2.5.1.1 The Include Files and Definitions Section 

This section describes the portion of the User Agent sample inquiry application 
program that lists the include files, local definitions, and data initialization for the 
program. 


/* . */ 

/* Include files needed for this program. */ 


#include 
^include 
flinclude 
^include 
^include 
#include 
#include 
^include 
^include 
#include 


<stdio.h> 

<sys/file.h> 
<sys/types.h> 
<sys/ioctl.h> 
<strings.h> 
<ctype.h> 
<sys/cam.h> 
<sys/dec_cam.h> 
<sys/uagt.h> 
<sys/scsi_all.h> 


/* CAM defines from the CAM document */ 

/* CAM defines for Digital CAM source files */ 
/* CAM defines for the UAgt driver */ 

/* CAM defines for ALL SCSI devices */ 
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/* .. V 

/* Local defines */ 

Jfdefine INQUIRY_JLEN 36 /* general inquiry length */ 00 

/* . V 


/* Initialized and uninitialized data. */ 
u_char buf[ INQUIRY_LEN ]; @ 


H This line defines a constant of 36 bytes for the length of the inquiry expected by 
the user from the SCSI device. 

@ This line declares a global character array, buf, with a size of 36 bytes as defined 
by the INQUIRYJLEN constant. 


2.5.1.2 The Main Program Section 

This section describes the main program portion of the User Agent sample inquiry 
application program. 

/* .-. V 

/* The main code path. The CCB/CDB and UAGT_CAM_CCB are set up for 
an INQUIRY command to the Bus/Target/Lun selected by the command 
line arguments. The returned INQUIRY data is displayed to the 
user if the status is valid. If the returned status indicates 
an error, the error is reported instead of the INQUIRY data. */ 

main(argc, argv) 
int argc; 
char *argv[]; 

{ 


pYt-prn void nri nf inn flataMi IT1 
extern void print_ccb_status() ; 

u_char id, targid, lun; /* from the command line */ 
int fd; /* unit number from the open */ HI 


UAGTCAMCCB ua_ccb; 
CCBSCSIIO ccb; 
ALL_INQ_CDB *inq; 


/* local uagt structure */ ® 
/* local CCB */ IS 
/* pointer for the CDB */ ® 


/* Make sure that all the arguments are there. */ ® 


if (argc != 4) { 

printf("SCSI INQ bus target lun\n"); 
exit(); 

1 

/* Convert the nexus information from the command line. */ 0 

id = atoi(argv[l]); 

targid = atoi(argv[2]); 
lun = atoi(argv[3]); 


0 These two forward references define routines that are used later in the program to 
print out the INQUIRY data or to print out the CAM status if there was an error. 

[2] The file descriptor for the User Agent driver returned by the open system call, 
which executes in Section 2.5.1.3. 
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§| This line declares an uninitialized local data structure, ua ccb, of the type 
UAGT_CAM_CCB, which is defined in the file /usr/sys/h/uagt. h. This 
structure is copied from user space into kernel space as part of the ioctl system 
call. Section 2.5.1.7 describes this procedure. 

0 This line declares an uninitialized local data structure, ccb, of the type 
CCB_SCSIIO , which is defined in the file /usr/sys/h/cam. h. The 
members of this structure needed for the XPTJSCSI JO request are filled in 
Section 2.5.1.4. The members of this structure needed for die INQUIRY 
command are filled in Section 2.5.1.5. 

0 This line declares a pointer, inq, to a data structure, ALL_INQ_CDB, which is 
defined in the file /usr/sys/h/scsi_all. h. This structure is filled in 
Section 2.5.1.5. 

|f§ This section of code makes sure the user entered the correct number of 
arguments. The user should have entered the string inq, followed by three 
numeric characters representing the bus, target, and LUN to be checked for a 
valid status. 

0 This section of code converts the numeric characters entered and assigns them, in 
order, to bus, target, and LUN. 


2.5.1.3 The User Agent Open Section 

This section describes the portion of the User Agent sample inquiry application 
program where the User Agent is opened. 

/* Open the User Agent driver and report any errors. */ 

if ((fd = open("/dev/cam", 0_RDWR, 0)) < 0 ) Q] 

{ 

perror("Error on CAM UAgt Open:"); 
exit(1); 

] 

0 The program attempts to open the User Agent device special file, /dev/cam, 
with the 0_RDWR flag, which allows reading and writing. If the file descriptor 
returned by the open system call indicates that the open failed by returning a 
negative value, < 0, the program reports an error and exits. Otherwise, the 
program opens the device. 


2.5.1.4 Filling in XPT.SCSI JO Request CCB J4EADER Fields 

This section describes the portion of the User Agent sample inquiry application 
program where the members of the CCB_HEADER needed for an XFT_SCSI JO 
request are filled in. 


/* Set up the CCB for an XPT_SCSI_IO request. The INQUIRY command 

will be sent to the device, instead of sending an XPT_GDEV_TYPE. */ 

/* Set up the CAM header for the XPT_SCSI_IO function. */ 

ccb.cam_ch.my_addr = (struct ccb_header *)&ccb; /* "Its" address */0] 
ccb.camch.camccblen = sizeof(CCB_SCSIIO); /* a SCSI I/O CCB */ 

ccb.cam_ch.cam_func_code = XPT_SCSI_IO; /* the opcode */ 

ccb.cam_ch.cam_path_id = id; /* selected bus */ [2 
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ccb.cam_ch.cam_target_id = targid; /* selected target */ 

ccb.cam_ch.cam_target_lun = lun; /* selected lun */ 

/* The needed CAM flags are : CAMDIRIN - The data will come from 
the target, CAM_DIS_ADTOSENSE - Do not issue a REQUEST SENSE packet 
if there is an error. */ 


ccb.cam_ch.cam_flags = CAM_DIR_IN | CAM_DIS_AUTOSENSE; §j 

U This section of code fills in some of the CCBJHEADER fields of the SCSI I/O 
CCB structure defined as ccb, for processing by the XPT layer. The structure 
was declared in Section 2.5.1.2. 

B These three lines assign the bus, target, and LUN to the corresponding fields in 
the CCB_HEADER structure. 

EH This line sets the necessary CAM flags for the INQUIRY: CAM_DIR_IN, which 
specifies that the direction of the data is incoming; and 

CAM_DIS_AUTOSENSE, which disables the autosense feature. These flags are 
defined in /usr/sys/h/cam. h. 


2.5.1.5 Filling in INQUIRY Command CCBJHEADER Fields 

This section describes the portion of the User Agent sample inquiry application 
program where the members of the CCBJHEADER needed for the INQUIRY 
command are filled in. This is the structure that is passed to the XPT layer by the 
User Agent driver. 


/* Set up the rest of the CCB for the INQUIRY command. */ 

ccb.cam_data_ptr = &buf[0]; /* where the data goes */ 01 

ccb.cam_dxfer_len = INQUIRYLEN; /* how much data */ 

ccb.cam_timeout = CAM_TIME_DEFADLT; /* use the default timeout */£8 
ccb.camcdblen = sizeof( ALL_INQ_CDB ); /* how many bytes for inquiry MU 


/* Use a local pointer to access the particular fields in the INQUIRY 
CDB. */ 


inq = (ALL_INQ_CDB *)&ccb.cam_cdb_io.cam_cdb_bytes[0]; 0 


inq->opcode = ALL_INQ_OP; 
inq->evpd - 0; 
inq->lun - 0; 
inq->page = 0; 

inq->alloc_len = INQUIRYJLEN; 
inq->control - 0; 


/* inquiry command */ (3 
/* no product data */ 

/* not used in SCSI-2 */ 

/* no product pages */ 

/* for the buffer space */ 
/* no control flags */ 


Q] This line sets the cam_data_ptr member of the SCSI I/O CCB structure to the 
address of the first element in the buf array, which is defined as 36 bytes in 
Section 2.5.1.1. 

® This line specifies using the default timeout, which is the value assigned to the 
CAM_TIME_DEFAULT constant. This constant is set in the 
/usr/sys/h/cam. h file to indicate that the SIM layer’s default timeout is to 
be used. The current value of the SIM layer’s default timeout is five seconds. 

® This line sets the length of the Command Descriptor Block in the CCB to the 
length of an inquiry CDB.. The inquiry CDB, ALL_INQ_CDB, which is defined 
in the /usr/sys/h/scsi_all. h file, is six bytes. 
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SI This line assigns the inq pointer, which is type ALL_INQ_CDB, to the address 
of the cam_cdb_bytes member of the CDB_UN union. This union is defined 
in /usr/sys/h/cam. h as the cam_cdb_io member of the SCSI I/O CCB 
structure. 

IS These lines use the inq pointer to access the fields of the cam_cdb_bytes 
array within the ccb structure as though it is an ALL_INQ_CDB structure. The 
ALL_INQ_CDB structure is defined in the /usr/sys/h/scsi_all. h file. 


2.5.1.6 Filling In the UAGT_CAM_CCB Fields 

This section describes the portion of the User Agent sample inquiry application 
program where the members of the UAGT_CAM_CCB structure are filled in for the 
ioctl call. This is the structure that is passed to the User Agent driver. 


/* Set up the fields for the User Agent Ioctl call. */ 

uaccb.uagtccb = (CCB_HEADER *)&ccb; /* where the CCB is */ Q] 

ua_ccb.uagt_ccblen = sizeof(CCB_SCSIIO); /* how many bytes to pull in */ @ 

ua_ccb.uagt_buffer « sbuf[0]; /* where the data goes */ @ 

ua_ccb.uagt_buflen = INQOIRY_LEN; /* how much data */ 3 

/* no Autosense data */ (S 

/* no Autosense data */ 

/* CDB is in the CCB */ IS 
/* CDB is in the CCB */ 

U This line initializes the uagt_ccb member of the ua_ccb structure with the 
address of the local CCB_HEADER structure, ccb. 

SI This line sets the length of the uagt_ccblen member to the length of the SCSI 
I/O CCB structure that will be used for this call. 

This line initializes the uagt_buf f er member with the user space address of 
the array buf, which was allocated 36 bytes in Section 2.5.1.1. 

This line initializes the uagt_buf len member with the value of the constant 
INQUIRY_LEN, which is the number of bytes of inquiry data that will be 
returned. 

@ These two lines reflect that the autosense features are turned off in the CAM 
flags. 

IS These two lines reflect that the Command Descriptor Block information is in the 
SCSI I/O CCB structure filled in Section 2.5.1.4. 

2.5.1.7 Sending the CCB to the CAM Subsystem 

This section describes the portion of the User Agent sample inquiry application 
program where the ccb is sent to the CAM subsystem. 


i 

i 


ua_ccb.uagt_snsbuf = (u_char *)NtJLL; 
ua_ccb.uagt_snsLen = 0; 
ua_ccb.uagt_cdb ■= (CDB_UN *)NULL; 
ua_ccb.uagt_cdblen = 0; 


/* Send the CCB to the CAM subsystem using the User Agent driver, 
and report any errors. */ 

if( ioctl(fd, OAGT_CAM_IO, (caddr_t)Sua_ccb) < 0 ) B 
{ 

perror("Error on CAM DAGT Ioctl:"); 

close(fd); /* close the CAM file */ E 

exit(l); 
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} 


/* If the CCB completed successfully, then print out the INQUIRY 
information; if not, report the error. */ 

if (ccb.cam_ch.cam_status I= CAM_REQ_CMP) 

{ 

print_ccb_status( &(ccb.cam_ch) ); /* report the error values */ 0 

} 

else 

t 

printinqdata( &buf[0] ); /* report the INQUIRY info */ 3 

) 

5 

HI This line passes the local UAGT_CAM_CCB structure, ua_ccb, to the User 
Agent driver, using the ioctl system call. The arguments passed are the file 
descriptor returned by the open system call; the User Agent ioctl command, 
UAGT_CAM_IO, which is defined in the /usr/sys/h/uagt. h file; and the 
contents of the ua ccb structure. The User Agent driver copies in the SCSI I/O 
CCB and sends it to the XPT layer. When the I/O completes, the User Agent 
returns to the application program, returning status within the ua_ccb structure. 

0 If the ioctl call fails, this code displays an error message, closes the device 
special file, /dev/cam, and exits. 

0 If the CAM status is anything other than CAM_REQ_CMP, indicating the 
request completed, an error message is printed indicating the CAM status 
returned. 

H If the request completes, the print_inq_data routine is called to display the 
INQUIRY data. 


2.5.1.8 Print INQUIRY Data Routine 

This section of the User Agent sample inquiry application program converts the rest 
of the fields of inquiry data to a human-readable form and sends it to the user’s 
screen. 

/* Define the type and qualifier string arrays as globals to allow for 
compile-time initialization of the information. */ 


caddrt periphtype[] = { 
"Direct-access", 
"Sequential-access", 
"Printer", 
"Processor", 
"Write-once", 
"CD-ROM", 

"Scanner", 

"Optical memory", 
"Medium changer", 

"Communications", 
"Graphics Arts" 

); /* Same as OA */ 

/* Reserved */ 

/* Unknown */ 

caddr_t periph_qual[] = { 
"Device supported, 
"Device supported, 


/* Peripheral Device Type */ 
/* OOh V 
/* Olh */ 

/* 02h */ 

/* 03h */ 

/* 04h */ 

/* 05h */ 

/* 06h */ 

/* 07h V 
/* 08h */ 

/* 09h */ 

/* OAh */ 

/* OBh */ 

/* OCh - lEh V 
/* lFh */ 

/* Peripheral Qualifier */ 
is (may be) connected", /* 000b */ 
is not connected", /* 001b */ 
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"<Reserved qualifier*", /* 010b */ 

"No device supported for this Lun" /* 011b */ 

}; /* Vendor specific */ /* lxxb */ 

/* . V 


/* Local routine to print out the INQUIRY data to the user. */ 
void 

printinqdata( ip ) ffl 
ALL_INQ_DATA *ip; 

t 

char vendorid[9]; Q 
char prod_id[17]; 
char prod rev lvl[5]; 
caddr_t periphtypeptr, periph_qual_ptr; 
int ptype; 

/* Make local copies of the ASCII text, so that it can be NULL 
terminated for the printf() routine. */ 

strncpy(vendor_id, (caddr_t)ip->vid, 8); (jj) 
vendor_id[ 8] = '\0'; 

strncpy<prod_id, (caddr_t)ip->pid, 16); 
prod_id[16] - '\0'; 

strncpy(prod_rev_lvl, (caddr_t)ip->revlevel, 4); 
prod_rev_lvl[4] = '\0'; 

/* Convert sparse device type and qualifier values into strings */ 

ptype = ip->dtype; @ 
periph_type_ptr = "Reserved"; 

if (ptype == OxlF) periph_type_ptr = "Unknown"; 
if (ptype == OxOB) ptype = OxOA; 

if (ptype <= OxOA) periph_type_ptr = periphtype[ptype]; 

periph_qual_ptr = "<vendor Specific qualifier*"; 
if (ip-*pqual <= 3) periph_qual_ptr = periph_qual[ip-*pqual]; 

printf("periph Device Type « 0x%x = %s Device\n", @ 
ip-> dtype, periph_type_ptr); 
printf("Periph Qualifier = Ox%X = %s\n", ip-*pqual, 

periphqualptr); 

printf("Device Type Modifier = 0x*X\tRMB = 0x%X = Medium %s\n", 
ip-*dmodify, ip-*rmb, (ip-*rmb?"is removable": 

"is not removable")); 

printf("ANSI Version - 0x%X\t\tECMA Version - 0x%X\n", 
ip-*ansi, ip-*ecma); 

printf("ISO Version « Ox%X\t\tAENC = Ox%X\tTrmIOP = 0x%X\n", 
ip-*iso, ip-*aenc, ip-*trmiop); 

printf("Response Data Format « Ox%X\tAddit Length •= 0x%d\n", 
ip-*rdf, ip-*addlen); 

printf("SftRe - 0x%XCmdQue - 0x%X\tLinked = 0x*X\tSync - 0x%x\n", 
ip-*sftre, ip-*cmdque, ip-*linked, ip-*sync); 
printf("Wbusl6 - 0x%X\tWbus32 = 0x%X\tRelAdr •» 0x%X\n", 
ip-*wbusl6, ip-*wbus32, ip-*reladdr); 
printf("Vendor Identification - %s\nProduct Identification « %s\n", 
vendor_id, prod_id ); 
printf("Product Revision Level - %s\n\n", 
prod_rev_lvl); 
fflush(stdout); @ 

) 
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HI This line declares the print_inq_data function that prints out the INQUIRY 
data for a valid nexus. The function’s argument, ip, is a pointer to the 
ALL_INQ_DATA structure defined in the /usr/sys/h/scsi_all. h file. 

E These three lines declare three character arrays to contain the Vendor ID, the 
Product ID, and the Product revision level to be displayed. Each array is declared 
with one extra byte to hold the NULL string terminator. 

E This section copies the ALL_INQ_DATA member, vid, into the local array 
vendor_id; die ALL_INQ_DATA member, pid, into the local array 
prod id; and the ALL_INQ_DATA member, revlevel, into the local array, 
prod_rev_lvl. The arrays are passed to the standard C library function, 
strncopy, which copies the data and then terminates each string copy with a 
NULL, so that it can be output to the printf function in the format desired. 

0 This section converts the device type and qualifier values into human-readable 
words. The conversions are performed on defined and undefined numeric 
combinations. 

E This section decodes and displays the inquiry data as hexadecimal numbers and 
strings. 

E This line calls the standard C I/O function, f flush, to write out the data from 
the internal buffers. 

2.5.1.9 Print CAM Status Routine 

This section describes the portion of the User Agent sample inquiry application 

program that defines the routine to print out the CAM status for an invalid nexus. 

/* . V 

/* Local routines and data structure to report in text and Hex 

form the returned CAM status. */ 


struct cam_statustable { U 

u_char cam_status; 

caddr_t statusjmsg; 

} cam_statustable[] = { E 

{ CAM_REQ_INPROG, "CCB request is in progress" }, 

{ CAM_REQ_CMP , "CCB request completed w/out error" }, 

{ CAM_REQ_ABORTED, "CCB request aborted by the host" }, 

{ CAM_UA_ABORT, "Unable to Abort CCB request" ], 

{ CAM_REQ_CMP_ERR, "CCB request completed with an err" }, 

{ CAM_BUSY, "CAM subsystem is busy" }, 

{ CAM_REQ_INVALID, "CCB request is invalid" }, 

{ CAM_PATH_INVALID, "Bus ID supplied is invalid" }, 

{ CAM_DEV_NOT_THERE, "Device not installed/there" ), 

{ CAM_UA_TERMIO, "Unable to Terminate I/O CCB req" }, 

{ CAM_SEL_TIMEOUT, "Target selection timeout" }, 

{ CAM_CMD_TIMEOUT, "Command timeout" ], 

{ CAMMSGREJECT_REC, "Reject received" }, 

{ CAM_SCSI_BUS_RESET, "Bus reset sent/received" J, 

{ CAM_UNCOR_PARITY, "Parity error occured" ], 

{ CAM_AUTOSENSE_FAIL, "Request sense cmd fail" }, 

{ CAM_NO_HBA, "No HBA detected Error" }, 

{ CAM_DATA_RUN_ERR, "Overrun/underrun error" }, 

{ CAM_UNEXP_BUSFREE, "BUS free" }, 

{ CAM_SEQUENCE_FAIL, "Bus phase sequence failure" } , 

{ CAM_CCB_LEN_ERR, "CCB length supplied is inadaquate" } r 

{ CAM_PROVIDE_FAIL, "To provide requ. capability" ], 

{ CAM_BDR_SENT, "A SCSI BDR msg was sent to target" }, 


{ CAM_REQ_TERMIO, "CCB request terminated by the host" }, 
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{ CAM_LUN_INVALID, "LUN supplied is invalid" }, 

{ CAM_TID_INVALID, "Target ID supplied is invalid" }, 

{ CAM_FUNC_NOTAVAIL, "Requested function is not available" }, 

{ CAM_NO_NEXUS, "Nexus is not established" }, 

{ CAM_IID_INVALID, "The initiator ID is invalid" }, 

{ CAM_CDB_RECVD, "The SCSI CDB has been received" ], 

{ CAM_SCSI_BUSY, "SCSI bus busy" }, 

{ CAM_SIM_QFRZN, "The SIM queue is frozen" }, 

{ CAM_AUTOSNS_VALID, "Autosense data valid for target" } 

}; 

int camstatusentrys - sizeof(cam_statustable) / \ 

sizeof(cam_statustable[0]); S 


char * 

camstatus ( camstatus ) SI 

register u_char cam_status; 

t 

register struct cam_statustable *cst ■= cam_statustable; @ 
register entrys; 

for( entrys - 0; entrys < cam_statusentrys; cst++ ) { E 
if( cst->cam_status == cam_status ) { 
return( cst->status_msg ); 

} 

} 

return( "Unknown CAM Status" ); 

} 

void 

print_ccb_status(cp) @ 

CCB_HEADER *cp; 

{ 

printf( "camstatus - 0x%X\t <%s%s%s)\n", cp->cam_status, 

((cp->cam_status & CAM_AUTOSNS_VALID) ? "AutoSns Valid-" : "" ), 

((cp->cam_status & CAM_SIM_QFRZN) ? "SIM Q Frozen-" : "" ), 
camstatus( cp->cam_status & CAM_STATUS_MASK )); 
fflush(stdout); E 

} 

U This line defines an array of structures. It is declared as a global array to allow 
compile-time initialization. Each structure element of the array contains two 
members, cam_status, the CAM status code, and status_msg, a brief 
description of the meaning of the status code. The CAM status codes and 
messages are defined in the /usr/sys/h/cam. h file. 

IH These lines initialize the CAM status array with the status values and their text 
equivalents. 

SI This line declares an integer variable whose contents equal the size of the total 
CAM status array divided by the size of an individual array element. This integer 
is the number of the element in the array. 

0 The next two lines define a function that returns a pointer to a text string with the 
cam_status field of the CCB_HEADER as an argument. The cam_status 
member is declared as a register variable so that its values are stored in a machine 
register for efficiency. 

SI This line declares a register structure pointer to point to each element of the CAM 
status array and initializes it to point to the beginning of the CAM status array. 

A local register variable, entrys, will be used to traverse the CAM status array. 

IS This section of code examines each element in the array, incrementing cst until 
a match between the status from the CCB and a status value in the array is found, 
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in which case the address of the CAM status description string, statusjmsg, is 
returned. If all the elements are examined without a match, the "Unknown CAM 
Status" message address is returned. 

H The next two lines define a routine that uses a pointer to the CCBJHEADER 
structure of the INQUIRY CCB and calls the C library routine, printf, to print 
out the hexadecimal value and the appropriate description of the CAM status 
returned. 

H This line calls the standard C I/O function, f flush, to write out the data from 
the internal buffers. 


2.5.1.10 Sample Output for a Valid Nexus 

This section contains an example of the output of the User Agent sample inquiry 
application program when the user enters a valid nexus. 

#inq 000 


Periph Device Type = 0x0 
Device Type Modifier = 0x0 
ANSI Version = 0x1 
ISO Version = 0x0 
Response Data Format = 0x1 
SftRe = 0x0 CmdQue = 0x0 

Wbusl6 = 0x0 Wbus32 = 0x0 
Vendor ID = DEC @ 

Product ID = RZ56 (C) DEC 1 

Product Rev Level = 0300 0 


Periph Qualifier = 0x0 0 
RMB = 0x0 

ECMA Version = 0x0 
AENC = 0x0 TrmlOP = 0x0 

Addit Length = 0x31 
Linked = 0x0 Sync = 0x1 
RelAdr = 0x0 


0 See the American National Standard for Information Systems, Small Computer 
Systems Interface - 2 (SCSI - 2), X3T9/89-042 for a description of each of the 
fields of the inquiry data returned. 


0 This line shows the value of the vendor_id variable declared in the 

print_inq_data routine in Section 2.5.1.8 as a local copy of the text string. 

SI This line shows the value of the prod_id variable declared in the 

print_inq_data routine in Section 2.5.1.8 as a local copy of the text string. 

0 This line shows the value of the prod_rev_lvl variable declared in the 
print_inq_data routine in Section 2.5.1.8 as a local copy of the text string. 


2.5.1.11 Sample Output for an Invalid Nexus 

This section contains an example of the output of the User Agent sample inquiry 
application program when the user enters an invalid nexus. 

#inq 020 

cam_status - 0x4A (SIM Q Frozen-Target selection timeout) Q) 

0 This line shows that the contents of the cam status member of the 

CCB_HEADER structure returned was CAM_SIM_QFRZN, which indicates a 
lack of response from the specified nexus. See the cam_statustable in 
Section 2.5.1.9. 
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2.5.2 Sample User Agent Scanner Driver Program 

This section contains the User Agent sample scanner program, cscan. c, with 
annotations to the code. It also contains the cscan. h file, which defines the 
WINDOW_PARAM_BLOCK structure used in the program. 


2.5.2.1 Scanner Program Header File 

This section describes the header file, cscan. h, that contains definitions of 
structures for the program to use. 

/* cscan.h Header file for cscan.c (CAM Scanner driver) 28-Oct-1991 */ 

/* Scanner Window Parameter Block definition; all multi-byte quantities 
are defined as unsigned bytes due to the need to store the values in 
swapped order. */ 


typedef struct { 

u_char rsvdl[6]; /* Reserved bytes in Header: Must Be Zero */ 

uchar WDBLen[ 2]; /* Number of Window Parameter bytes following */ [jfl 

u_char WID; /* Window ID: Must Be zero */ 

u_char rsvd2; /* Reserved bytes in Header: Must Be Zero */ 

u_char XRes[2]; /* x-axis resolution: MUST be same as YRes */ 

u_char YRes[2]; /* Y-axis resolution: MUST be same as XRes */ 

u_char UpLeftX[4]; /* Upper left X positon of scan window */ 

u_char 0pLeftY[4]; /* Upper left Y positon of scan window */ 

u_char Width[4); /* Scan width (Y-axis length) */ 

u_char Length[4]; /* Scan length (X-axis length) */ 

uchar Bright; /* Brightness: Must Be Zero */ 

uchar Thresh; /* Threshold: Must Be Zero */ 

u_char Contrast; /* Contrast: Must Be Zero */ 

u_char ImgTyp; /* Image type: 0 = bi-level mono; 2 = multi-level 

mono; 3 = bi-level full color; 5 = multi¬ 
level full color; others reserved */ 
uchar PixBits; /* Bits per pixel: 1 = bi-level; 4 = 16 shades; 

8 = 256 shades; others reserved */ 
u_char HalfTone[2];/* Halftone Pattern: Must Be Zero */ 
uchar PadTyp:3; /* Padding type for non-byte pixels: MUST BE 1 */ 
uchar rsvd3:4; /* Reserved bits: Must Be Zero */ 

u_char Revlmg:l; /* 0 = normal image; 1 = reverse image */ 
uchar BitOrder[2];/* Bit ordering: Must Be Zero */ 
u_char CompTyp; /* Compression type: Must Be Zero */ 

u char CompArg; /* Compression argument: Must Be Zero */ 

uchar rsvd4[6]; /* Reserved: Must Be Zero */ 

u_char HdrSel; /* Header select (return with data): 0 « no header; 

1 - return header with data; others reserved */ 
uchar ColorSel; /* Color select (selects color to use when doing a 

mono-color scan): 0 = default to Green; 1 = 
scan using Red; 2 = scan using Green; 3 - 
scan using Blue; others reserved */ 
u_char ImgCorr; /* Image data correction method: 0 - default to 

normal; 1 « soft image; 2 *> enhance (low); 

3 » enhance (high); others reserved */ 
u_char ThreshR; /* Threshold level, Red: 0 = default level */ 

u_char ThreshG; /* Threshold level, Green: 0 - default level */ 

u_char ThreshB; /* Threshold level, Blue: 0 = default level */ 

uchar ShtTyp:l; /* Sheet type: 0 » reflection; 1 - transparency */ 

u_char rsvd5:3; /* Reserved bits: Must Be Zero */ 

uchar ShtDen:4; /* Sheet density (transparency): 0 = normal; 1 = 

light; 2 = dark; others reserved */ 


}WINDOW_PARAM_BLOCK; 
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H The length in bytes of a single scan window descriptor. The first 48 bytes are 
defined in the American National Standard for Information Systems, Small 
Computer Systems Interface - 2 (SCSI - 2), X3T9/89-042 and the remaining bytes 
are vendor-specific. The specific structure members used may depend on the 
scanner device. 

2.5.2.2 The Include Files Section 

This section, which is the beginning of the cscan program, describes the portion of 
the User Agent sample scanner program that lists the include files for the program. 

/*. v 

/* Include files needed for this program. */ 

♦include <stdio.h> 

♦include <unistd.h> 

♦include <sys/file.h> 

♦include <sys/types.h> 

♦include <sys/ioctl.h> 

♦include <sys/uio.h> 

♦include <strings.h> 

♦include <ctype.h> 

♦include <math.h> 

♦include <sys/cam.h> /* CAM defines from the CAM document */ 

♦include <sys/dec_cam.h> /* CAM defines for Digital CAM source files */ 

♦include <sys/uagt.h> /* CAM defines for the OAgt driver */ 

♦include <sys/scsi_all.h> /* CAM defines for ALL SCSI devices */ 

♦include "cscan.h" /* Scanner structure definitions */ 

2.5.2.3 The CDB Setup Section 

This section describes the portion of the User Agent sample scanner program that 
defines the CDBs for the program. 

/* The Define Window Parameters CDB (10 bytes). */ 
typedef struct { 


u_char 

opcode; 


/* 

24 hex 


V 

u_char 


5, 

/* 

5 bits reserved 


*/ 


lun 

3; 

/* 

logical unit number 

*/ 

u_char 


8; 

/* 

Reserved byte 


V 

uchar 


8; 

/* 

Reserved byte 


V 

u_char 


8; 

/* 

Reserved byte 


V 

u_char 


8; 

/* 

Reserved byte 


V 

uchar 

param_len2; 

/* 

MSB parameter list 

length 

V IS 

uchar 

param_lenl; 

/* 

parameter list 

length 

V 

u_char 

param_len0; 

/* 

LSB parameter list 

length 

V 

u_char 

control; 


/* 

The control byte 


V 


}SCAN_DEF_WIN_CDB; 

/* The Define Window Parameters op code */ 

#define SCAN_DEF_WIN_OP 0x24 

/* The Read (data or gamma table) CDB (10 bytes). */ 


typedef struct { 

u_char opcode; /* 28 hex */ 

u_char : 5, /* 5 bits reserved */ 

lun : 3; /* logical unit number */ 

u_char tran_type; /* transfer data type: */ 
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/* 

0= 

=data, 3=gamma 

V 12! 

u_ 

char 

: 8; 

/* 

Reserved byte 

V 

u_ 

char 

tran_idl; 

/* 

MSB 

transfer identification 

V i 

u_ 

char 

tran_id2; 

/* 

LSB 

trans id: 

V 




/* 

0 

“data, 1/2/3= gamma 

*/ 

u_ 

char 

param_len2; 

/* 

MSB 

parameter list length 

*/ 

u_ 

char 

paramlenl; 

/* 


parameter list length 

V 

u_ 

char 

paramlenO; 

/* 

LSB 

parameter list length 

V 

u 

char 

control ; 

/* 

The 

control byte 

V 


1SCAN_READ_CDB; 

/* The Read (data or gamma table) op code */ 
#define SCAN READ OP 0x28 


BO The parameter list length members specify the number of bytes sent during the 
DATAOUT phase. The parameters are usually mode parameters, diagnostic 
parameters, and log parameters that are sent to a target. If set to 0 (zero), no data 
is to be transferred. 

l2l The types of data that are to be read. The choices are: image data scan lines or 
gamma correction table data. 

ES These two bytes are used with the transfer type byte to indicate that the data to be 
read is image scan lines, 0 (zero), or one of the following types of gamma 
correction table data: red, 1; green, 2; or blue, 3. 


2.5.2.4 The Definitions Section 

This section describes the portion of the User Agent sample scanner program that 
specifies the local definitions and initializes data. 


/* . */ 

/* Local defines */ 

#define SENSE_LEN18 /* max sense length from scanner */ 0] 

/* . V 


/* Initialized and uninitialized data. */ 
u_char sense[ SENSE_LEN ]; @ 


ED This line defines a constant of 18 bytes for the length of the sense data from the 
scanner. 

l2l This line declares a character array, sense, with a size of 18 bytes as defined by 
the SENSE_LEN constant. 


2.5.2.5 The Main Program Section 

This section describes the main program portion of the User Agent sample scanner 
program. 

/*.-.-.v 

/* The main code path. The CCB/CDB and UAGT_CAM_CCB are set up for the 
DEFINE WINDOW PARAMETERS and READ commands to the Bus/Target/LUN. */ 

main(argc, argv,envp) 
int argc; 
char *argv[J; 
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char *envp[]; 

{ 


/* . V 

/* Local variables and structures */ 


extern void clear_mem(); Q] 
extern void swap_short_store(); 
extern void swap_long_store(); 


uchar id, targid, lun; /* from envir variable SCAN-NEXUS */ 12 

char *cp; 
int nexus; 


int fd; 
int od; 

char FileHead[200]; 
int i, n; 
u_char *bp; 
int retry_cnt; 
int resetflag; 


/* unit number for the CAM open */ 0 
/* unit number for the file open */ S 
/* buffer for file header info */ 

/* general usage byte pointer */ 

/* error retry counter */ 

/* flag to indicate reset tried */ 


double Xwid, Ylen; /* scan area in inches */ SI 

u_short WXYRes; /* variables for window calulations */ 

u_long WWidth, WLength, WinPix, LineBytes, TotalBytes; @ 
u_char WHdrSel; ® 

UAGT_CAM_CCB ua_ccb_sim_rel; /* local uagt structure */ SI 

CCB_RELSIM ccb_sim_rel; /* local CCB */ @ 

OAGT_CAM_CCB ua_ccb_reset_dev; /* local uagt structure */ Bfi] 

CCB_RESETDEV ccb_reset_dev; /* local CCB */ QS 


OAGT_CAM_CCB ua_ccb; 
CCB_SCSIIO ccb; 
SCAN_DEF_W1N_CDB *win; 
SCAN_READ_CDB *read; 


/* local uagt structure */ B2 
/* local CCB */ 03 
/* pointer for window def CDB */ Q3 
/* pointer for read CDB */ QS1 


WINDOW_PARAM_BLOCK Window; /* parameter block, window def */ Q3 

u_char ReadData[ 400*12*3 ]; /* Max bytes/line */ 52 
uchar *RDRp, *RDGp, *RDBp; /* Red, Green, Blue pointers */ 
uchar WriteData[ 400*12*3 ]; /* Max bytes/line */ 53 

u_char *WDp; /* WriteData pointer */ 


H] These forward references declare routines that are used later in the program. The 
routines are defined in Section 2.5.2.14. 

H The bus, target, and LUN are specified in octal digits in the SCAN-NEXUS 
environment variable. The value for the LUN should be 0 (zero). 

HI The file descriptor for the User Agent driver returned by the open system call, 
which executes in Section 2.52.1. 

|4j The file descriptor for the output file returned by the open system call, which 
executes in Section 2.52.1. 

® Real values to contain the X and Y dimensions of the scan window. 

H Variables to hold calculated information about the scan window. 

0 Variable to hold the flag byte indicating whether a window header is to be 
returned with the data. The value of the variable is stored in the HdrSel 
member of the WINDOW_PARAM_BLOCK structure is set to 1. The 
WINDOW_PARAM_BLOCK is defined in Section 2.5.2.1. 
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IS This line declares an uninitialized local data structure, ua_ccb_sim_rel, to be 
used for the RELEASE SIM QUEUE CCB command. 

IS This line declares an uninitialized local data structure, ccb_sim_rel, of the 
type CCB_RELSIM , which is defined in the file /usr/sys/h/cam. h. 

flQ] This line declares an uninitialized local data structure, ua_ccb_reset_dev, to 
be used for the BUS DEVICE RESET CCB command. 

(Til This line declares an uninitialized local data structure, ccb_reset_dev, of the 
type CCB_RESETDEV , which is defined in the file /usr/sys/h/cam. h. 

US This line declares an uninitialized local data structure, ua_ccb, of the type 
UAGT_CAM_CCB, which is defined in the file /usr/sys/h/uagt. h. This 
structure is copied from user space into kernel space as part of the ioctl system 
call. 

fl3l This line declares an uninitialized local data structure, ccb, of the type 
CCB_SCSIIO , which is defined in the file /usr/sys/h/cam. h. 

im This line declares a pointer to the data structure SCAN_DEF_WIN_CDB , which 
is defined in Section 2.5.2.3. 

fiSl This line declares a pointer to the data structure SCAN_READ_CDB , which is 
defined in Section 2.5.2.3. 

HU This line declares an uninitialized local data structure, Window, of the type 
WINDOW_PARAMJBLOCK , which is defined in Section 2.5.2.I. 

fl7l This line declares an array to contain a scan line of the maximum size that can be 
read, which is 14,400 bytes. This array is used to read a scan line from the 
scanner. 

Rl This line declares an array large enough to contain the maximum-size scan line, 
which is 14,400 bytes. This array is used to write the scan line, converted to 3- 
byte pixels, to the output file. 


2.5.2.6 The Nexus Conversion Section 

This section describes the portion of the User Agent sample scanner program where 
the nexus information contained in the SCAN-NEXUS environment variable is 
converted to the values for bus, target, and LUN. 

/* Find the environment variable SCAN-NEXOS. If not found, return 
error message. If found, convert the nexus information from the 
variable to bus, target ID and LON values. Return an error 
message if any of the values are not octal digits. */ 

nexus « 0; /* Reset valid data flag */ 

for (i“0; envpfi] i«= NOLL; i++) 

{ 

cp - envp [ i ]; Q] 

if (strncmp(cp,"SCAN-NEXOS-",11) »■ 0)/* Find environment variable */ 

l 

nexus « -1; /* Set tentative flag */ 

cp +» 11; /* Advance to data */ 

if (*cp < 'O' || *cp > ’T) break; @ 

id *= (uchar)(*cp++) - (u_char) (' 0'); 

if (*cp++ l= ' ') break; 

if (*cp < '0' || *cp > '7') break; 

targid = (u_char)(*cp++) - (u_char)('0'); 

if (*cp++ 1= ' ') break; 
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if (*cp < '0' || *cp > '7') break; 
lun = (u_char)(*cp) - (u_char)('0'); 

nexus =1; /* Set good data flag */ 

} 

} 

if (nexus == -1) 0 

{ 

printf("Invalid SCAN-NEXUS; set to octal digits 'bus target lun'\n"); 
exit(l); 

} 

if (nexus *»= 0) 0 

{ 

printf("Set environment variable SCAN-NEXUS to 'bus target lun' (octal\ 

digits)\n\n"); 

exit(l); 

] 

printf("Scanner nexus set to: bus %d, target %d, LUN %d\n\n",id, \ 

targid, lun); Isl 


Q] This section scans through all of the environment variables passed to the program 
by the system, looking for the variable SCAN-NEXUS. 

|2| This section checks to make sure SCAN-NEXUS contains octal digits for bus, 
target, and LUN. 

E! This error message appears if the digits are not octal. 

HI This error message appears if SCAN-NEXUS is not set. 

IS This message displays the values for bus, target, and LUN. 

2.5.2.7 The Parameter Assignment Section 

This section describes the portion of the User Agent sample scanner program that 
assigns the parameters entered by the user on the command line to the appropriate 
variables and opens the necessary files. 

/* Make sure that the correct number of arguments are present. 

If not, return an error message with usage information. */ 

if (argc 1= 5) { [J 

printf("Usage is: cscan XYres Xwid Ylen outfile\n"); 
printf(” XYres is integer pix/inch; Xwid & Ylen are real \ 

inches\n\n"); 

exit(); 

} 

/* Convert the parameter information from the command line. */ 

WXYRes - atoi(argv[l] ); /* X & Y resolution */ 

Xwid - atof(argv[2]); /* X width in inches */ 

Ylen - atof(argv[3]); /* Y length in inches */ 

/* Verify that the X & Y resolution is one of the legal values */ 

switch (WXYRes) @ 

{ 

case 25: 
case 150: 
case 200: 
case 300: 
case 400: 
break; 
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default: 

printf("Illegal X & Y resolution; must be 25, 150, 200, \ 

300, 400\n"); 

exit(l) ; 

} 

/* Verify that the X width is positive and less than 11.69 inches */ H) 

if (Xwid < 0 || Xwid > 11.69) 

{ 

printf("X width must be positive and less than 11.69 inches\n"); 
exit(1); 


/* Verify that the Y length is positive and less than 17.00 inches */ 

if (Ylen < 0 || Ylen > 17.00) 

{ 

printf("Y length must be positive and less than 17.00 inches\n"); 
exit(l); 


/* Open the output file {"truncating" it if it exists) and report */ 

/* any errors. */ 0 

if ((od - open(argv[4], 0_WR0NLY|0_CREAT|0_TRUNC, 0666)) < 0 ) 

f 

perror("Error on Output File Open"); 
exit(1); 

J 

/* Open the User Agent driver and report any errors. */ 

if ((fd = open("/dev/cam", 0_RDWR, 0)) < 0 ) 

{ 

perror("Error on CAM UAgt Open"); 
exit(l); 

] 

ED The user enters the X and Y scan resolutions in pixels per inch, the width (X) 
and length (Y) of the scan area in inches, and the name of the output file on the 
command line. 

[3 This section checks for the legal scan resolutions the user can enter. 

13 These two sections check that the user entered legal values for X and Y. 

0 These two sections open the User Agent driver and the output file. 

2.5.2.8 The Data Structure Setup Section 

This section describes the portion of the User Agent sample scanner program that sets 
up the data structures for the XPT_REL_SIMQ and XPT_RESET_DEV commands. 

/* - - Begin static setups of SIMQ Release and Device Reset structures -- */ 

/* Set up the CCB for an XPT_REL_SIMQ request. */ 

/* Set up the CAM header for the XPT_REL_SIMQ function. */ 

ccb_sim_rel.cam_ch.my_addr = {struct ccbheader *)&ccb_sim_rel; 

/* "Its" address */ S3 

ccb_sim_rel.cam_ch.cam_ccb_len = sizeof(CCB_RELSIM); /* a SIMQ release */ 
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XPT_REL_SIMQ; /* the opcode */ 
id; /* selected bus */ 

targid; /* selected target */ 

lun; /* selected lun */ 

/* The needed CAM flags are: CAM_DIR_NONE - No data will be transferred. */ 

ccbsimrel.cam_ch.camflags = CAM_DIR_NONE; 

/* Set up the fields for the Dser Agent loctl call. */ 

uaccbsimrel.uagtccb = (CCB_HEADER *)&ccb_sim_rel; 

/* where the CCB is */ @ 

ua_ccb_sim_rel.uagt_ccblen - sizeof(CCB_RELSIM); /* bytes in CCB */ 
uaccbsimrel.uagtbuffer - (uchar *)N0LL; /* no data */ 

uaccbsimrel.uagtbuflen =0; /* no data */ 

ua_ccb_sim_rel.uagt_snsbuf « (u_char *)NOLL; /* no Autosense data */ 
uaccbsimrel.uagt_snslen = 0; /* no Autosense data */ 

ua_ccb_sim_rel.uagtcdb = (CDB_ON *)N0LL; /* CDB is in the CCB */ 

uaccbsimrel.uagtcdblen =0; /* CDB is in the CCB */ 

/* Set up the CCB for an XPT_RESET_DEV request. */ 

/* Set up the CAM header for the XPT_RESET_DEV function. */ 

ccb_reset_dev.cam_ch.my_addr » (struct ccb_header *)&ccb_reset_dev; 

/* "Its" address */ @ 

ccb_reset_dev.cam_ch.cam_ccb_len - sizeof(CCB_RESETDEV);/* a SCSI I/O CCB */ 
ccb_reset_dev.cam_ch.cam_func_code - XPT_RESET_DEV; /* the opcode */ 
ccb_reset_dev.cam_ch.cam_path_id = id; /* selected bus */ 

ccb_reset_dev.cam_ch.cam_target_id = targid; /* selected target */ 

ccbresetdev.cam_ch.cam_target_lun = lun; /* selected lun */ 

/* The needed CAM flags are: CAM_DIR_NONE - No data will be transferred. */ 

ccb_reset_dev.cam_ch.camflags = CAM_DIR_NONE; 

/* Set up the fields for the Dser Agent loctl call. */ 

ua_ccb_reset_dev.uagt_ccb = (CCB_HEADER *)&ccb_reset_dev; 

/* where the CCB is */ @ 

ua_ccb_reset_dev.uagt_ccblen ■= sizeof(CCBRESETDEV);/* bytes in CCB */ 
ua_ccb_reset_dev.uagt_buffer = (u_char *)N0LL; /* no data */ 

ua_ccb_reset_dev.uagt_buflen =0; /* no data */ 

uaccbresetdev.uagtsnsbuf « (u_char *)N0LL; /* no Autosense data */ 

ua_ccb_reset_dev.uagtsnslen =0; /* no Autosense data */ 

uaccbresetdev.uagtcdb - (CDB_0N *)N0DL; /* CDB is in the CCB */ 

ua_ccb_reset_dev.uagt_cdblen =0; /* CDB is in the CCB */ 

/* -- End of static setups of SIMQ Release and Device Reset structures -- */ 

HI This section of code fills in some of the CCB_HEADER fields of the RELEASE 
SIM QUEUE CCB structure defined as ccb_sim_rel, for the 
XPT_REL_SIMQ command. The structure was declared in Section 2.S.2.5 

HI This section of code fills in some of the CCB_HEADER fields of the 

CCB_RELSIM structure defined as ua_ccb_sim_rel, for the RELEASE SIM 
QUEUE CCB command. The structure was declared in Section 2.5.2.5 

EH This section of code fills in some of the CCBJHEADER fields of the 
CCB_RESETDEV structure defined as ccb_reset_dev, for the 
XPT_RESET_DEV command. The structure was declared in Section 2.52.5 


ccb_sim_rel. cam_ch. cam func code <= 
ccb_sim_rel.camch.cam_path_id = 
ccb sim rel. cam ch. cam_target_id ** 
ccbsimrel.cam_ch.camtargetlun = 
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H This section of code fills in some of the CCB_HEADER fields of the 

CCB_RESETDEV structure defined as ua_ccb_reset_dev, for the BUS 
DEVICE RESET CCB command. The structure was declared in Section 2.5.2.S 


2.5.2.9 The Window Parameters Setup Section 

This section describes the portion of the User Agent sample inquiry application 
program that fills in the scan window parameters and sends a SCSI SET WINDOW 
PARAMETERS command to the scanner. 

/* Pill in window parameters for scanner and send DEFINE WINDOW */ 

/* PARAMETERS command to the scanner. Note that the X&Y resolution */ 

/* and the X width and Y length are specified on the command line. */ 


WWidth = Xwid*(double)WXYRes; 
WLength = Ylen*(double)WXYRes; 
WHdrSel = 0; 

#if de f NO_HEADER_FOR_NOW 
WHdrSel - 1; 

#endif 


/* X width inches to pixels */ fi] 
/* Y length inches to lines */ 

/* Don't return header */ 

/* Return header w. data */ 


WinPix - WWidth*WLength; /* Pixels in window */ 0 

LineBytes « WWidth*3; /* Full color, 8-bit pixels */ 

TotalBytes = WHdrSel*256 + winPix*3; /* Full color, 8-bit pixels */ 

printf("Window parameters:\n"); 0 

printf(" width = %6d pixels/line, Length = %6d lines; Total = %10d pixels\n", 
WWidth, WLength, WinPix); 

printf(" Bytes/line = %6d; Total bytes/image = %10d\n", LineBytes, 

TotalBytes); 


/* Fill in window parameters for scanner and send DEFINE WINDOW PARAMETERS */ 

/* command to the scanner. */ 

clear_mem( swindow, sizeof (Window)) ,• /* clear whole DWP block */ S 

swap_short_store(swindow.WDBLen[0], 0x2F); /* REQUIRED length @ 
swap_short_store(swindow.XRes[0), WXYRes); /* X and Y MOST BE THE SAME */ 
swap_short_store(swindow.YRes[0], WXYRes); /* X and Y MOST BE THE SAME */ 

/* upper Left X&Y left at zero */ 
swap_long_store(fiWindow.Width[0], WWidth); 
swap_long_store(swindow.Length[0], WLength); 

Window.ImgTyp =5; /* Multi-level full color */ S) 

Window.PixBits - 8; /* 8-bit pixels */ 0 

Window.PadTyp - 1; /* REQUIRED value */ H 

Window.Revlmg - 1; /* Reverse ~ 0,0,0 » black */ £) 

Window.HdrSel « WHdrSel; /* Set return header control */ 53 

/* All other values left at zero */ 


/* Display current contents of bytes in window parameter block */ 52 


printf("window Parameter block (in hex):\n"); 

for( i-0, bp”(u_char *)&Window; i < sizeof(Window); i++, bp++) { 
printf("%.2x ", *bp); 
if (i — 7) printf("\n"); 
if (i «« 8+21) printf("\n"); 

} 

printf("\n\n" ); 

HI This section converts the X and Y values entered from the command line in 
inches into pixels. The value of WXYRes is an int; however, the values of 
Xwid and Ylen are floating point values. To perform the calculations to 
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determine the values of WWidth, the number of pixels per line, and WLength, 
the number of scan lines, the value of WXYRes must be converted to a real 
number. For example, if the value entered for X were 4.5 and the resolution 
selected were 300, WWidth would equal 1,350 pixels per line. If the value 
entered for Y were 3.5, the result would be 1,050 scan lines. 

@ This section of the program calculates the number of bytes in the scan window 
based on the total number of pixels. For example, the calculation using the 
previous figures would yield 1,417,500 pixels as the value of WinPix. To 
calculate the number of bytes per line, WWidth is multiplied by 3, which is the 
number of bytes per pixel. The total number of bytes in the scan window, using 
the figures in the example, would be 4,252,500 bytes. 

@ These lines display the results of the calculations. 

SI This line calls the clear_mem function to set the local 

WINDOWJPARAMJBLOCK structure, Window, to 0’s (zeroes) in preparation 
for storing the byte values in swapped order. The WINDOW_PARAM_BLOCK 
structure was defined in Section 2.5.2.1. The clear_mem function is defined in 
Section 2.5.2.14. 

@ This section of code calls the functions that put the bytes of short and long 
integer values into big-endian storage. The functions are defined in Section 
2.5.2.14. 

M This line sets the image type for the scanner. The setting of 5 means multilevel, 
full color. 

E This line sets the number of bits per pixel. The setting of 8 means 256 shades. 

£1 This line sets the padding type for nonbyte pixels. The setting of 1 means pad 
with 0 (zero). 

M This line sets the reverse image. The setting of 1 means white pixels are 
indicated by 1 (one) and black pixels are indicated by 0 (zero). 

flOl This line sets the selection for returning a header with the data. The setting of 
WHdrSel was set to 0 (do not include the header). 

QI1 This section displays the contents of the bytes in the window parameter block. 

2.5.2.10 CCB Setup for the DEFINE WINDOW Command 

This section describes the portion of the User Agent sample scanner program where 

the fields of the CCB_HEADER needed for an XPT_SCSI_IO request are filled in. 

/* Set up the CCB for an XPT_SCSI_IO request. The DEFINE WINDOW 
PARAMETERS command will be sent to the device. */ 

/* Set up the CAM header for the XPT_SCSI_IO function. */ 

ccb.cam_ch.my_addr - (struct ccbheader *)&ccb; /* "Its" address */ HI 
ccb.camch.camccblen - sizeof(CCB_SCSII0); /* a SCSI I/O CCB */ 

ccb.camch.camfunccode « XPT_SCSI_IO; /* the opcode */ 

ccb.cam_ch.cam_path_id - id; /* selected bus */ 

ccb.cam_ch.cam_target_id » targid; /* selected target */ 

ccb.cam_ch.cam_target_lun ■= lun; /* selected lun */ 

/* The needed CAM flags are: CAM_DIR_OUT - The data will go to the target. */ 
ccb.camch.camflags = CAM_DIR_OUT; 
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/* Set up the rest of the CCB for the DEFINE WINDOW PARAMETERS command. */ 

ccb.cam_data_ptr = (uchar *)4Window; /* where the parameters are */ 03 
ccb.camdxferlen «= sizeof(Window); /* how much data */ @ 

ccb.cam_timeout ■= CAM_TIME_DEFAtJLT; /* use the default timeout */ 3 
ccb.cam_cdb_Ien = sizeof(SCAN_DEF_WIN_CDB); /* how many bytes for cdb */ 0 
ccb.cam_sense_ptr - &sense[0]; /* Autosense data area */ 

ccb.camsenselen = SENSE_LEN; /* Autosense data length */ 

/* Use a local pointer to access the fields in the DEFINE WINDOW PARAMETERS 
CDB. */ 


win «= (SCANDEFWINCDB *)&ccb.cam_cdb_io.cam_cdb_bytes[0]; @ 


clear_mem(win,sizeof(SCAN_DEF_WIN 
win->opcode = SCAN_DEF_WIN_OP; 
win->lun = lun; 

win->param_lenO - sizeof(Window); 
win->param_lenl = 0; 
win->param_len2 « 0; 
win->control = 0; 


CDB)); /* clear all bits in CDB */ 0 
/* define window command */ E 
/* lun on target */ 

/* for the buffer space */ 

/* no control flags */ 


/* Set up the fields for the Dser Agent Ioctl call. */ E 

ua_ccb.uagt_ccb = (CCBHEADER *)&ccb; /* where the CCB is */ B2 

ua_ccb.uagt_ccblen = sizeof(CCB_SCSIIO); /* how many bytes to gather */ Q3] 
ua_ccb.uagt_buffer = (u_char *)SWindow; /* where the parameters are */ Q2 

ua_ccb.uagt_buflen = sizeof (Window); /* how much data */ QH 


ua_ccb.uagt_snsbuf = ssense[0]; 
ua_ccb.uagt_snslen = SENSE_LEN; 
uaccb.uagtcdb = (CDB_0N *)NDLL; 
ua_ccb.uagt_cdblen = 0; 


/* Autosense data area */ B2 
/* Autosense data length */ 
/* CDB is in the CCB */ B3 
/* CDB is in the CCB */ 


H This section of code fills in some of the CCB_HEADER fields of the SCSI I/O 
CCB structure defined as ccb, for processing by the XPT layer. The structure 
was declared in Section 2.5.2.5. 

0 This line assigns the cam_data_ptr member of the local CCB_SCSIIO data 
structure, ccb, to the address of the Window parameter block. The Window 
parameter block structure was filled in Section 2.5.2.9. 

51 This line sets the data transfer length to the length of the Window structure. 

0 This line specifies using the default timeout, which is the value assigned to the 
CAM_TIME_DEFAULT constant. This constant is set in the 
/usr/sys/h/cam. h file to indicate that the SIM layer’s default timeout is to 
be used. The current value of the SIM layer’s default timeout is five seconds. 

51 This line sets the length of the cam_cdblen member to the length of the 
SCAN_DEF_WIN_CDB structure. 

51 This line assigns the win pointer, which is type SCAN_DEF_WIN_CDB, to the 
address of the cam_cdb_bytes member of the CDB_UN union. This union is 
defined in /usr/sys/h/cam. h as the cam_cdb_io member of the SCSI I/O 
CCB structure. 

E This line calls the clear_mem function to clear the local 

SCAN_DEF_WIN_CDB structure in preparation for storing the values needed for 
the DEFINE WINDOW operation. The SCAN_DEF_WIN_CDB structure was 
defined in Section 2.5.2.3. The clear_mem function is defined in Section 
2.5.2.14. 
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!§ These lines use the win pointer to access the bytes of the cam_cdb_bytes 
array as though it is a SCAN_DEF_WIN_CDB structure. The 
SCAN_DEF_WIN_CDB structure is defined in Section 2.5.2.3 

B This section of the code assigns the program address of the CCB into the CCB 
pointer member and the program address of the Window parameter block into the 
data pointer member of the ua_ccb structure of type UAGT_CAM_CCB, as 
defined in the /usr/sys/h/uagt. h file. This structure is copied from user 
space into kernel space as part of the ioctl system call that is executed in 
Section 2.5.2.11 This structure was declared in Section 2.5.2.3. 

US This line initializes the uagt_ccb member of the ua_ccb structure with the 
address of the local CCB_HEADER structure, ccb. 

03] This line sets the length of the uagt_ccblen member to the length of the SCSI 
I/O CCB structure that will be used for this call. 

fl2l This line initializes the uagt_buf f er member with the user space address of 
the Window parameter block. 

OS This line initializes the uagt_buf len member with the number of bytes in the 
Window parameter block. 

03 These two lines reflect that the autosense features are turned on in the CAM flags. 

QH These two lines reflect that the Command Descriptor Block information is in the 
SCSI I/O CCB structure filled in Section 2.5.2.5. 


2.5.2.11 The Error Checking Section 

This section describes the portion of the User Agent sample scanner program that 
attempts to set the window parameters and recover from possible scanner errors. 

/* Send the CCB to the CAM subsystem using the User Agent driver. 

If an error occurs, report it and attempt corrective action. */ 

retry_cnt = 10; /* initialize retry counter */ 

reset_flag = 0; /* initialize reset flag */ 


retry_SWP: 

printf("Attempt to Set Window Parameters\n"); 

if( ioctl(fd, OAGT_CAM_IO, (caddr_t)&ua_ccb) < 0 ) 0] 

t 

perror("Error on CAM OAgt Ioctl to Define Window Parameters"); 
close(fd); /* close the CAM file */ 

exit(l); 

} 

/* If the CCB did not complete successfully then report the error. */ 

if (ccb.camch.camstatus l- CAM_REQ_CMP) 

{ 

print_ccb_status("CAM OAgt Define Window Ioctl", 

&(ccb.camch) ); /* report the error values */ 

printf(" cam_scsi_status « 0x%.2X\n", ccb.camscsistatus); (H 

/* 1st check if the SIM Queue is frozen. If it is, release it. */ 

if (ccb.cam_ch.cam_status & CAM_SIM_QFRZN) { 
printf("Attempt to release SIM Queue\n"); 

if( ioctl(fd, OAGT CAM IO, (caddr_t)fiuaccbsimrel) < 0 ) { |j§ 
perror("Error on CAM UAgt Release Sim Queue Ioctl"); 
close(fd); /* close the CAM file */ 
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exit(l); 


} 

/* If the Release Sim Q CCB did not complete successfully then 
report the error and exit. */ 

print_ccb_status("CAM UAgt Release SIM Queue Ioctl", 

S(ccb_sim_rel.cam_ch) ); /* report the error values */ 

if (ccb_sim_rel.cam_ch.cam_status 1= CAMREQCMP) { 
print_ccb_status("CAM UAgt Release SIM Queue Ioctl", 
&(ccb_sim_rel.cam_ch) ); /* report the error values */ 0 
close(fd); /* close the CAM file */ 

exit(l); 

} 

] 

/* Next, if we haven't done one yet, attempt a device reset to clear any 
device error. */ 

if (reset_flag++ == 0) 

{ 

printf("Attempt to Reset the scanner\n") ; 

if( ioctl(fd, UAGT_CAM_IO, (caddr_t)&ua_ccb_reset_dev) < 0 ) { (§ 
perror("Error on CAM UAgt Device Reset Ioctl"); 
close(fd); /* close the CAM file */ 

exit(l); 

} 

/* If the Reset Device CCB did not complete successfully then 
report the error and exit. */ 

print_ccb_status("CAM UAgt Device Reset Ioctl", 
fi(ccb_reset_dev.cam_ch) ); /* report the error values */ 

if (ccb_reset_dev.cam_ch.cam_status i= CAM_REQ_CMP) { 0 
print_ccb_status("CAM UAgt Device Reset Ioctl", 
&(ccb_reset_dev.cam_ch) ); /* report the error values */ 

close(fd); /* close the CAM file */ 

exit(l); 

} 

/* Wait the 28 seconds that the scanner takes to come back to life 
after a reset; no use to do anything else. */ 

printf("Scanner was reset, wait 28 Seconds for it to recover...\n"); 
sleep(28); 


/* Last, count if all retries are used up. If not, try the SWP again. If so, 
give up and exit. */ 

printf("Retry counter value - %d\n",retry_cnt); 
if (retry_cnt-- > 0) goto retry_SWP; 

close(fd); /* close the CAM file */ 

exit(l); 

} 

else 

{ 

/* Output status information on success for debugging. */ 

printccbstatus("CAM UAgt SET WINDOW PARAMETERS Ioctl", 

s(ccb.cam_ch) ); /* report the error values */ 
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printf(" cam_scsi_status = 0x%.2X\n", ccb.cam_scsi_status); 
printf("\nWindow parameter set up successful\n"); 

} 

/* Output header information (magic number, informational comment, X and Y 
dimensions and maximum pixel values) to the data file and display it for 
the user. */ 

sprintf(FileHead,"P6\n\# X&Y resolution = %d dpi, %d pixels/line, \ 

%d lines", @ 

WXYRes,wwidth,WLength) ; 

sprintf(strchr(FileHead,NOLL),"\n%d %d 255\n",WWidth,WLength); 

write(od,FileHead,strlen(FileHead)) ; 

printf("File header data --\n%s\n",FileHead); 


03 This section of code attempts to set the window parameters. This line passes the 
local UAGT_CAM_CCB structure, ua ccb, to the User Agent driver, using the 
ioctl system call. The arguments passed are the file descriptor returned by the 
open system call; the User Agent ioctl command, UAGT_CAM_IO, which is 
defined in the /usr/sys/h/uagt. h file; and the contents of the ua_ccb 
structure. The User Agent driver copies in the SCSI I/O CCB and sends it to the 
XPT layer. When the I/O completes, the User Agent returns to the application 
program, returning status within the ua_ccb structure. 

SI If the CAM status is anything other than CAM_REQ_CMP, indicating the 
request completed, an error message is printed indicating the CAM status 
returned. 

SI This section of code attempts to clear the SIM queue if it is frozen. This line 
passes the local UAGT_CAM_CCB structure, ua_ccb_sim_rel, to the User 
Agent driver, using the ioctl system call. The arguments passed are the file 
descriptor returned by the open system call; the User Agent ioctl command, 
UAGT_CAM_IO, which is defined in the /usr/sys/h/uagt. h file; and the 
contents of the ua_ccb_sim_rel structure. The User Agent driver copies in 
the SCSI I/O CCB and sends it to the XPT layer. When the operation completes, 
the User Agent returns to the application program, returning status within the 
ua_ccb structure. 

0 If the CAM status is anything other than CAM_REQ_CMP, indicating the 
request completed, an error message is printed indicating the CAM status 
returned. An error message is displayed and the program exits. 

Is) This section of code attempts a device reset. This line passes the local 

UAGT_CAM_CCB structure, ua_ccb_reset_dev, to the User Agent driver, 
using the ioctl system call. The arguments passed are: the file descriptor 
returned by the open system call; the User Agent ioctl command, 
UAGT_CAM_IO, which is defined in the /usr/sys/h/uagt. h file; and the 
contents of the ua_ccb_reset_dev structure. The User Agent driver copies 
in the SCSI I/O CCB and sends it to the XPT layer. When the operation 
completes, the User Agent returns to the application program, returning status 
within the ua_ccb structure. 

0 If the CAM status is anything other than CAM_REQ_CMP, indicating the 
request completed, an error message is printed indicating the CAM status 
returned. An error message is displayed and the program exits. 

IZl If the scan window parameters were set up successfully, a portable pixmap P6 file 
is created. This section displays the X and Y resolutions in dots per inch, pixels 
per line, and number of lines, taking the values that were generated from the code 
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in Section 2.5.2.9. 


2.5.2.12 CCB Setup for the READ Command 

This section describes the portion of the User Agent sample inquiry application 
program that sets up the CCBs for a READ command. 

/* Set up the CCB for an XPT_SCSI_IO request. The READ (data) command will be 
sent to the device. */ 

/* Set up the CAM header for the XPT_SCSI_IO function. */ 

ccb.camch.myaddr = (struct ccb_header *)&ccb; /* "Its" address */ IS 
ccb.camch.camccblen « sizeof(CCBSCSIIO); /* a SCSI I/O CCB */ 

ccb.camch.camfunc_code = XPT_SCSI_IO; /* the opcode */ 

ccb.camch.cam_path_id = id; /* selected bus */ 

ccb.cam_ch.cam_target_id «* targid; /* selected target */ 

ccb.cam_ch.cam_target_lun - lun; /* selected lun */ 

/* The needed CAM flags are: CAM_DIR_IN - The data will come from the target. */ 

ccb.cam_ch.cam_flags = CAM_DIR_IN; 

/* Set up the rest of the CCB for the READ command. */ 

ccb.cam_data_ptr = (u_char *)ReadData; /* where the data goes */ 12 

ccb.cam_dxfer_len = LineBytes; /* how much data */ 

ccb.camtimeout = 100; /* use timeout of lOOSec */ 

ccb.cam_cdb_len = sizeof( SCAN_READ_CDB ); /* how many bytes for read */ [2j 

ccb.camsenseptr = &sense[0]; /* Autosense data area */ 

ccb.cam_sense_len = SENSE_LEN; /* Autosense data length */ 

/* Use a local pointer to access the fields in the DEFINE WINDOW PARAMETERS 
CDB. */ 

read = (SCAN_READ_CDB *)&ccb.cam_cdb_io.cam_cdb_bytes[0]; @ 

clear_mem(read, sizeof (SCAN_READ_CDB)); /* clear all bits in CDB */ S 

read->opcode = SCAN_READ_OP; /* define window command */ 

read->lun » lun; /* lun on target */ 

read->param_lenO = LineBytes&255; /* for the buffer space */ 

read->param_lenl = (LineBytes>>8)&255; 
read->param_len2 “ (LineBytes>>16)i255; 

read->control = 0; /* no control flags */ 

/* Set up the fields for the User Agent loctl call. */ 

uaccb.uagtccb = (CCBHEADER *)&ccb; /* where the CCB is */ g 

uaccb.uagtccblen = sizeof(CCB_SCSlIO); /* how many bytes to pull in */ 0 
uaccb.uagtbuffer *= ReadData; /* where the data goes */ @ 

ua ccb.uagt buflen - LineBytes; /* how much data */ Iflj 

uaccb.uagtsnsbuf « &sense[0]; /* Autosense data area */ m 

uaccb.uagtsnslen - SENSE_LEN; /* Autosense data length */ 

uaccb.uagtcdb - (CDB_UN *)NULL; /* CDB is in the CCB */ 031 

ua_ccb.uagt_cdblen - 0; /* CDB is in the CCB */ 

n «■ TotalBytes + strlen(FileHead) ; 

printf("Total bytes in file = %12d.\n", n); 

printf("\nRead data from scanner and write to file\n"); 
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EQ This section of code fills in some of the CCB_HEADER fields of the SCSI I/O 
CCB structure defined as ccb, for processing by the XPT layer. The structure 
was declared in Section 2.5.2.5. 

0 This line sets the cam_data_ptr to the address of the ReadData array 
defined in Section 2.5.2.5. 

0 This line sets the data transfer length to the length of the SCAN_READ_CDB 
structure. 

0 This line sets the read pointer, which is type SCAN_READ_CDB, to the 
address of the cam_cdb_len member of the CDB_UN union. This union is 
defined in /usr/sys/h/cam. h as the cam_cdb_io member of the SCSI I/O 
CCB structure. 

H This line calls the clear_mem function to clear the local SCAN_READ_CDB 
structure, read, in preparation for storing the values needed for the READ 
operation. The SCAN_READ_CDB structure was defined in Section 2.5.2.3. 

The clear_mem function is defined in Section 2.5.2.14. 

El These lines use the read pointer to access the bytes of the cam_cdb_bytes 
array as though they are in a SCAN_DEF_WIN_CDB structure. The 
SCAN_READ_CDB structure is defined in Section 2.5.2.3. 

0 This line sets the length of the uagt ccblen member to the length of the SCSI 
I/O CCB structure that will be used for this call. 

|j| This line sets the uagt_buf f er member of the ua_ccb structure. 

@ This line sets the size of the data buffer to the number of bytes contained in the 
buffer pointed to by the cam_data_ptr member of the ccb structure. 

S3 These two lines reflect that the autosense features are turned on in the CAM flags. 

HU These two lines reflect that the Command Descriptor Block information is in the 
SCSI I/O CCB structure filled in Section 2.5.2.5. 


2.5.2.13 The Read and Write Loop Section 

This section describes the portion of the program where the data is read, reformatted, 
and placed in the output buffer. 

/* ****************** Beginning of read/write loop ***************** */ 

for (i“0; i<WLength; i++) { 

printf(" Read scanner line number %8d\r",i); 
fflush(stdout); 0 

/* Send the CCB to the CAM subsystem via the User Agent driver, 
and report any errors. */ 

if( ioctl(fd, UAGT_CAM_IO, (caddr_t)&ua_ccb) < 0 ) @ 

l 

perror("\nError on CAM UAgt Ioctl to Read data line"); 
close(fd); /* close the CAM file */ 

exit(1); 

} 

/* If the CCB completed successfully then print out the data read, 
if not report the error. */ 

if (ccb.cam_ch.cam_status 1= CAM_REQ_CMP) 


2-30 CAM User Agent Modules 



{ 


printf("\n"); 

print_ccb_status("CAM UAgt Read data line Ioctl", 

&(ccb.cam_ch) ); /* report the error values */ 

printf{" cam_scsi_status = 0x%.2X\n", ccb.cam_scsi_status); 
close(fd); /* close the CAM file */ 
exit(1); 

} 

else 

{ 

#ifdef CUT_FOR_NOW 

printf(" Data line read successfully\n"); 

#endif 

/* Re-format the data from blocks of R, G and B data to tuples 
of (R,G,B) data for the data file. Set up pointers to the 
beginning of each of the blocks of the Red, the Green and the 
Blue data bytes and another pointer to the output buffer. 

Then loop, collecting one each of Red, Green and Blue, 
putting each into the output data buffer. */ @ 

RDRp = ReadData; /* Red bytes are first */ 

RDGp «= RDRp + WWidth; /* Green bytes are next */ 

RDBp = RDGp + WWidth; /* Blue bytes are last */ 

WDp = WriteData; 

for (n - 0 ; n < WWidth; n++) 

{ 

*WDp++ = *RDRp++; 

*WDp++ = *RDGp++; 

*WDp++ = *RDBp++; 

] 

/* Now write the re-formatted data to the output file. */ 

write(od,WriteData,LineBytes); /* write data to file */ 

} 

} /* ****************** End of read/write loop ***************** */ 
printf("\nSuccessful read and write to file\n"); 
close(fd); /* close the CAM file */ 
close(od); /* close the output file */ 


H This line calls the standard C I/O function, fflush, to force the scan line 
number to the user’s display. 

6) This section of code attempts to read a scan line. This line passes the local 
UAGT_CAM_CCB structure, ua_ccb, to the User Agent driver, using the 
ioctl system call. The arguments passed are the file descriptor returned by the 
open system call; the User Agent ioctl command, UAGT_CAM_IO, which is 
defined in the /usr/sys/h/uagt. h file; and the contents of the ua ccb 
structure. The User Agent driver copies in the SCSI I/O CCB and sends it to the 
XPT layer. When the I/O completes, the User Agent returns to the application 
program, returning status within the ua_ccb structure. 

0 The scan line read in contains all the red bytes, then all the green bytes, then all 
the blue bytes, in sequence. This section of code reformats the bytes into pixels 
for the output file by placing a red byte, then a green byte, then a blue byte 
together on the output file scan line. 
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2.5.2.14 The Local Function Definition Section 

This section describes the portion of the User Agent sample scanner program that 
defines functions used within the program. 

/* Local routines and data structure to report in text and Hex form the 
returned CAM status. */ 
struct camstatustable { B) 

uchar camstatus 

caddr_t status_msg 
) cam_statustable[] - { 

{ CAMREQINPROG, 

{ CAMREQCMP , 

{ CAMREQABORTED, 

{ CAM_UA_ABORT, 

[ CAM_REQ_CMP_ERR, 

{ CAM_BUSY, 

{ CAM_REQ_INVALID, 

{ CAM_PATH_INVALID f 
{ CAM_DEV_NOT_TH ERE, 

{ CAM_UA_TERMIO, 

{ CAM_SEL_TIMEOUT, 

{ CAM_CMD_TIMEOUT, 

{ CAM_MSG_REJECT_REC 
{ CAM_SCSI_BUS_RESET 
{ CAM_ONCOR_PARITY, 

[ CAM_AOTOSENSE_FAIL 
t CAM_NO_HBA, 

{ CAM_DATA_RDN_ERR, 

{ CAM_UNEXP_BOSFREE, 

{ CAM_SEQDENCE_FAIL, 

{ CAM_CCB_LEN_ERR, 

{ CAM_PROVIDE_FAIL, 

{ CAM_BDR_SENT, 

{ CAM_REQ_TERMIO, 

{ CAM_LUN_INVALID, 

{ CAM_TID_INVALID, 

{ CAM_FDNC_NOTAVAIL, 

{ CAMNONEXUS, 

{ CAM_IID_1NVALID, 

{ CAMCDBRECVD, 

{ CAM_SCSI_BDSY, 

} ; 

int cam_statusentrys ■ sizeof(cam_statustable) / 
sizeof(cam_statustable[0]); 
char * camstatus( cam_status ) 
register u_char camstatus; 

{ 

register struct cam_statustable *cst - camstatustable; 

register entrys; 

for( entrys * 0; entrys < camstatusentrys; cst++ ) { 
if( cst->cam_status •« cam_status ) { 
return( cst->status_msg ); 

J 

) 

return( "Unknown CAM Status" ); 

] 

void print_ccb_status(id_string,cp) @ 
char »id_string; 

CCB_HEADER *cp; 

{ 

register i; 

printf("Status from %sO,id_string); 


"CCB request is in progress" } 

"CCB request completed w/out error" }, 
"CCB request aborted by the host" }, 
"Unable to Abort CCB request" }, 

"CCB request completed with an err" }, 
"CAM subsystem is busy" 

"CCB request is invalid" 

"Bus ID supplied is invalid" 

"Device not installed/there" 

"Unable to Terminate I/O CCB req" 

"Target selection timeout" 

"Command timeout" 

"Reject received" 

"Bus reset sent/received" 

"Parity error occured" 

"Request sense cmd fail" 

"No HBA detected Error" 

"Overrun/underrun error" 

"BUS free" 

"Bus phase sequence failure" 

"CCB length supplied is inadaquate" }, 
"To provide requ. capability" ], 

"A SCSI BDR msg was sent to target" }, 
"CCB request terminated by the host" }, 
"LUN supplied is invalid" ], 

"Target ID supplied is invalid" }, 

"Requested function is not available" }, 
"Nexus is not established" }, 

"The initiator ID is invalid" }, 

"The SCSI CDB has been received" }, 

"SCSI bus busy" 


]. 
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printf(" cam_status » Ox%.2X (%s%s%s)0, cp->cam_status, 

((cp->cam_status & CAM_AUTOSNS_VALID) ? "AutoSns Valid-" : 

((cp->cam_status & CAM_SIM_QFRZN) ? "SIM Q Frozen-" : "" ), 
camstatus( cp->cam_status & CAM_STATOS_MASK )); 

if (cp->cam_status & CAM_AOTOSNS_VALID) { 

printf("AutoSense Data (in hex):0); 
for( i=0; i < SENSE_LEN; i++) 

printf("%.2X ", sensefi]); 
printf("0 ); 

J 

fflush(stdout); 

} 

void clear_mem(bp,n) /* Clear n bytes of memory beginning at bp */ §j 

u_char *bp; 
int n; 

C 

register i; 
register u_char *ptr; 

for(i=0, ptr=bp; i<n; i++, ptr++) *ptr = 0; 

} 

void swap_short_store(bp,val) /* Store short into byte-reversed storage */ 51 
u_char *bp; 
u_short val; 

{ 

u_short temp; 
register u_char *ptr; 

ptr = bp; /* Copy pointer */ 

*(bp++) = (u_char)(val>>8); /* Store high byte first */ 

*bp = (uchar)val; /* Then store low byte */ 

} 

void swap_long_store(bp,val) /* Store long into byte-reversed storage */ @ 

u_char *bp; 
u_long val; 

{ 

*(bp++) = (uchar)(val>>24); /* store high byte first */ 

*(bp++) = (u_char)(val>>16); 

*(bp++) * (u_char)(val>>8); 

*bp = (u_char)val; /* Store low byte last */ 

} 

U This function is described in Section 2.5.1.9. 

H] This function prints out the CCB status. 

This function clears out all the bits in an area of memory, such as a structure or 
an array, to be sure all are set to 0 (zero) and that there is no extraneous data 
before executing a SCSI/CAM command. 

H This function puts the bytes of a short (16-bit) integer value into big-endian 
storage to conform with SCSI byte ordering. 

® This function puts the bytes of a long (32-bit) integer value into byte-reversed 
storage to conform with SCSI byte ordering. 
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This chapter describes the common data structures, macros, and routines provided by 
Digital for SCSI/CAM peripheral device driver writers. These data structures, 
macros, and routines are used by the generic SCSI/CAM peripheral device driver 
routines described in Chapter 4. 

Using the common and generic routines helps ensure that your SCSI/CAM peripheral 
device drivers are consistent with the ULTRIX SCSI/CAM Architecture. See 
Chapter 11 if you plan to define your own SCSI/CAM peripheral device drivers. See 
Chapter 12 for information about the SCSI/CAM special I/O interface to process 
special SCSI I/O commands. 

If a SCSI/CAM device driver writer needs to understand all members of a structure, 
the complete structure is shown and each member described. If a SCSI/CAM device 
driver writer needs to understand only specific members of a structure, those 
members are listed in a table, and only those members are described. 

3.1 Common SCSI Device Driver Data Structures 

This section describes the SCSI/CAM peripheral common data structures. The 
following data structures are described: 

• PDRV_UNIT_ELEM, the Peripheral Device Unit Table 

• PDRV_DEVICE, the Peripheral Device Structure 

• DEV_DESC, the Device Descriptor Structure 

• MODESEL_TBL, the Mode Select Table Structure 

• DENSITY_TBL, the Density Table Structure 

• PDRV_WS, the SCSI/CAM Peripheral Device Driver Working Set Structure 


3.1.1 Peripheral Device Unit Table 

The Peripheral Device Unit Table is an array of SCSI/CAM peripheral device unit 
elements. The size of the array is the maximum number of possible devices, which 
is determined by the maximum number of SCSI controllers allowed for the system. 
The structure is allocated statically and is defined as follows: 


typedef struct pdrv_unit_elem { 

PDRV_DEVICE *pu_device; /* 
u_short pu_opens; /* 

u_short pu_config; /* 

/* 

u_char pu_type; /* 

J PDRV UNIT ELEM; 


Pointer to peripheral device structure 
Total number of opens against unit */ 
Indicates whether the device type */ 
configured at this address */ 

Device type - byte 0 from inquiry data 


V 


*/ 





The pu_device field is filled in with a pointer to a CAM-allocated peripheral SCSI 
device (PDRV_DEVICE) structure when the first call to the ccmn_open_unit 
routine is issued for a SCSI device that exists. 

3.1.2 Peripheral Device Structure 

A SCSI/CAM peripheral device structure, PDRV_DEVICE, is allocated for each 
SCSI device that exists in the system. This structure contains the queue header 
structure for the SCSI/CAM peripheral device driver CCB request queue. It also 
contains the Inquiry data obtained from a GET DEVICE TYPE CCB. Table 3-1 lists 
the members of the PDRV_DEVICE structure that a SCSI/CAM peripheral device 
driver writer using the common routines provided by Digital may use. Chapter 11 
shows the complete structure for those driver writers who are not using the common 
routines. 


Table 3-1: Members of the PDRV_DEVICE Structure 


Member Name 

Data Type 

Description 

pd_dev 

dev_t 

The major/minor device number pair that 
identifies the bus number, target ID, and 
LUN associated with this SCSI device. 
Passed to the common open routine. 

pd_bus 

u_char 

SCSI target’s bus controller number. 

pd_target 

u_char 

SCSI target’s ID number. 

pd_lun 

u_char 

SCSI target’s logical unit number. 

pd_flags 

u_long 

May be used to indicate the state of a SCSI 
device driver. 

pd_state 

u_char 

May be used for recovery. 

pd_abort_cnt 

u_char 

May be used for recovery. 

pd_dev_inq [ INQLEN] 

u_char 

Inquiry data obtained from issuing a GET 
DEVICE TYPE CCB. 

*pd_dev_desc 

DEV_DESC 

Pointer to the SCSI device descriptor. 

pd_specific 

caddr_t 

Pointer to device-specific information. 

pd_spec_size 

u_long 

Size of device-specific information 
structure. 

*(pd_recov_hand)() 

void 

Recovery handler. 

pd_lk_device 

lock_t 

SMP lock for the device. 


The pd_specif c field is filled in with a pointer to an allocated structure that 
contains device-specific information. 

3.1.2.1 The pd_dev Member 

The major/minor device number pair that identifies the bus number, target ID, and 
LUN associated with this SCSI device. 
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3.1.2.2 The pd_spec_slze Member 

The size, in bytes, of the device-specific information structure passed from the SCSI 
device driver to the common open routine. 

3.1.3 Device Descriptor Structure 

There is a read-only SCSI device descriptor structure, DEV_DESC, defined for 
each device supported by Digital. A user may supply a new DEV_DESC structure 
by adding it to /usr/sys/data/cam_data. c and relinking the kernel. The 
DEVJDESC structure follows: 

typedef struct dev_desc { 

u_char dd_pv_name[IDSTRING_SIZE]; 

/* Product ID and vendor string from */ 

/* Inquiry data */ 

u_char dd_length; /* Length of dd_pv_name string */ 

u_char dd_dev_name[DEV_NAME_SIZE]; 

/* Device name string - see defines */ 

/* in devio.h */ 

u_long dd_device_type; /* Bits 0-23 contain the device */ 

/* class, bits 24-31 contain the */ 

/* SCSI device type */ 
struct pt_info *dd_def_partition; 

/* Default partition sizes - disks */ 
u_long dd_block_size; /* Block/sector size */ 
u_long dd_max_record; /* Maximun transfer size in bytes */ 

/* allowed for the device */ 

DENSITY_TBL *dd_density_tbl; 

/* Pointer to density table - tapes */ 

MODESEL_TBL *dd_modesel_tbl; 

/* Mode select table pointer - used */ 

/* on open and recovery */ 

u_long dd_flags; /* Option flags (bbr, etc) */ 

u_long dd_scsi_optcmds;/* Optional commands supported */ 
u_long dd_ready_time; /* Time in seconds for powerup dev ready */ 
u_short dd_que_depth; /* Device queue depth for devices */ 

/* which support command queueing */ 
u_char dd_valid; /* Indicates which data length */ 

/* fields are valid */ 

u_char dd_inq_len; /* Inquiry data length for device */ 

u_char dd_req_sense_len; 

/* Request sense data length for */ 

/* this device */ 

}DEV_DESC; 


3.1.4 Mode Select Table Structure 

The Mode Select Table Structure is read and sent to the SCSI device when the first 
call to the SCSI/CAM peripheral open routine is issued on a SCSI device. There can 
be a maximum of eight entries in the Mode Select Table Structure. Chapter 11 
contains a description of each structure member. The definition for the Mode Select 
Table Structure, MODESEL_TBL, follows: 

typedef struct modesel_tbl { 
struct ms_entry{ 

u_char ms_page; /* Page number */ 

u_char *ms_data; /* Pointer to Mode Select data */ 

u_char ms_data_len; /* Mode Select data length */ 
u_char ms_ent_sp_pf;/* Save Page and Page format bits */ 

/* BIT 0 l=Save Page, */ 

/* 0=Don't Save Page */ 
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/* BIT 1 l=SCSI-2, 0=SCSI-1 */ 


}ms_entry[MAX_OPEN_SELS] ; 
}MODESEL_TBL; 


3.1.5 Density Table Structure 

The Density Table Structure allows for the definition of eight densities for each type 
of SCSI tape device unit. Chapter 11 contains a description of each structure 
member. The definition for the Density Table Structure, DENSITY_TBL, follows: 

typedef struct density_tbl { 
struct density! 


u_char 

u_char 

den_flags; 
den_density_code; 

/* 

VALID, ONE_FM etc */ 

u_char 

dencompresscode; 

/* 

Compression code if supported */ 

u_char 

den_speed_setting; 

/* 

for this density */ 

u_char 

den_buffered_setting; 

/* 

Buffer control setting */ 

u_long 

den_blocking; 

/* 

0 variable etc. */ 


}density[MAX_TAPE_DENSITY]; 
}DENSITY_TBL; 


3.1.5.1 The den_blocking Member 

The den_blocking member contains the blocking factor for this SCSI tape device. 
A NULL (0) setting specifies that the blocking factor is variable. A positive value 
represents the number of bytes in a block, for example, 512 or 1024. 


3.1.6 SCSI/CAM Peripheral Device Driver Working Set Structure 

The SCSI I/O CCB contains cam_pdrv_ptr, a pointer to the SCSI/CAM 
peripheral device driver working set area for the CCB. This structure is also 
allocated by the XPT when the xpt_ccb_alloc routine is called to allocate a 
CCB. The PDRV_WS structure follows: 


typedef struct 


pdrv_ws [ 


struct pdrv_ws 
struct pdrv_ws 
CCB_SCSIIO 
u_long 
u_long 
u char 


u_char 
PDRV WS; 


*pws_flink; /* Linkage of working set CCBs * 

*pws_blink; /* that we have queued */ 

*pws_ccb; /* Pointer to this CCB. */ 

pws_flags; /* Generic to driver */ 

pws_retry_cnt; /* Retry count for this request 
*pws_pdrv; /* Pointer to peripheral device 

/* structure */ 

pws_sense_buf[DEC_AUTO_SENSE_SIZE]; 


3.1.6.1 The pwsjllnk Member 

The pws_f link member of the pdrv_ws structure is a pointer to the forward link 
of the working set CCBs that have been queued. 

3.1.6.2 The pws_blink Member 

The pws blink member of the pdrv_ws structure is a pointer to the backward 
link of the working set CCBs that have been queued. 
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3.1.6.3 The pws_ccb Member 

The pws ccb member is a pointer to this CCB. The CCB header is filled in by the 
common routines. 


3.2 Common SCSI Device Driver Macros 

The SCSI/CAM peripheral device driver common macros are supplied by Digital for 
SCSI device driver writers to use. These macros are defined in the 
/usr/sys/h/pdrv. h file. There are two categories of macros: 

• Macros to obtain identification information about each SCSI device 

• Locking macros 

Table 3-2 lists each identification macro name, its call syntax, and a brief description 
of its purpose. 

Table 3-2: Common Identification Macros 


Name 

Syntax 

Description 

DEV_BUS_ID 

DEV_BUS_ID(dev) 

Returns the bus ED of the 
device that is identified in the 
major/minor device number 
pair. 

DEV_TARGET 

DEV_TARGET(dev) 

Returns the target ID of the 
device that is identified in the 
major/minor device number 
pair. 

DEV.LUN 

DEV_LUN{dev) 

Returns the target LUN of the 
device that is identified in the 
major/minor device number 
pair. 

GET_PDRV_UNIT_ELEM 

GET_PDRV_UNIT_ELEM(dev) 

Returns the Peripheral Device 
Unit Table entry for the device 
that is identified in the 
major/minor device number 
pair. 

GET_PDRV_PTR 

GET_PDRV_PTR(dev) 

Returns the pointer to the 
Peripheral Device Structure for 
the device that is identified in 
the major/minor device number 
pair. 


Table 3-3 lists each locking macro name, its call syntax, and a brief description of its 
purpose. 
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Symmetric Multiprocessing (SMP) is not enabled in this release. 


Table 3-3: Common Lock Macros 


Name 

Syntax 

Description 

PDRV_INIT_LOCK 

PDRV_INIT_LOCK(pd) 

Initializes the Peripheral 

Device Structure lock. 

PDRV_IPLSMP_LOCK 

PDRV_IPLSMP_LOCK(pd, 
lk_type, saveipl) 

Raises the IPL and locks the 
Peripheral Device Structure. 

PDRVJPLSMPJJNLOCK 

PDRV_IPLSMP_UNLOCK(pd, 
saveipl) 

Unlocks the Peripheral Device 
Structure and lowers the IPL. 

PDRV_SMP_LOCK 

PDRV_SMP_LOCK(pd) 

Locks the Peripheral Device 
Structure. 

PDRV_SMP_SLEEPUNLOCK 

PDRV_SM P_S LEE PUNLOCK(chan, 
pri, pd) 

Unlocks the Peripheral Device 
Structure. 


3.3 Common SCSI Device Driver Routines 

The SCSI/CAM peripheral common device driver routines can be allocated into 
categories as follows: 

• Initialization, open, and close routines, which handle the initialization of 
SCSI/CAM peripheral device drivers and the common open and close of the 
drivers. The following routines are in this category: 

- ccmn_init 

- ccmn_open_unit 

- ccmn_close_unit 

• CCB queue manipulation routines, which manage placing and removing CCBs 
from the appropriate queues as well as aborting and terminating I/O for SCSI I/O 
CCBs on the queue’s active list. The following routines are in this category: 

- ccmn_send_ccb 

- ccmn_rem_ccb 

- ccmn_abort_que 

- ccmn_term_que 

• CCB allocation, build, and deallocation routines, which allocate CCBs, fill in the 
common portion of the CCB_HEADER, as well as create and send specific types 
of CCB requests to the XPT. The following routines are in this category: 

- ccmn_get_ccb 

- ccmn_rel_ccb 

- ccmn_io_ccb_bld 
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- ccmn_gdev_ccb_bld 

- ccmn_sdev_ccb_bld 

- ccmn_sasy_ccb_bld 

- ccmn_rsq_ccb_bld 

- ccmn_pinq_ccb_bld 

- ccmn_abort_ccb_bld 

- ccmn_term_ccb_bld 

- ccmn_bdr_ccb_bld 

- ccmn_br_ccb_bld 

• Common routines to build and send SCSI I/O commands, which are called during 
the open or recovery sequence of a device. The calling routine must sleep while 
the command completes, if necessary. The following routines are in this 
category: 

- ccmn_tur 

- ccmn_start_unit 

- ccmn_mode_select 

• CCB status routine, which assigns CAM status values to a few general 
classifications. The following routine is in this category: 

- ccmn_ccb_status 

• Buf structure pool allocation and deallocation routines, which allocate and 
deallocate buf structures from the buffer pool. The following routines are in this 
category: 

- ccmn_get_bp 

- ccmn_rel_bp 

• Data buffer pool allocation and deallocation routines, which allocate and 
deallocate data buffer areas from the pool. The following routines are in this 
category: 

- ccmn_get_dbuf 

- ccmn_rel_dbuf 

• Routines to perform miscellaneous operations. The following routines are in this 
category: 

- ccmn_ccbwait 

- ccmn_SysSpecialCmd 

- ccmn_DoSpecialCmd 

- ccmn_errlog 

Descriptions of the routines with syntax information, in ULTRIX reference page 
format, are included in alphabetical order in Appendix C. 
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3.3.1 Common I/O Routines 

This section describes the common SCSI/CAM peripheral device driver initialization 
and I/O routines. Table 3-4 lists the name of each routine and gives a summary 
description of its function. The sections that follow contain a more detailed 
description of each routine. 


Table 3-4: Common I/O Routines 


Routine 

Summary Description 

ccmn_init 

ccmn_open_unit 

ccmn_close_unit 

initializes the XPT and the unit table lock structure 
handles the common open for all SCSI/CAM peripheral 
device drivers 

handles the common close for all SCSI/CAM peripheral 
device drivers 


3.3.1.1 The ccmnjnlt Routine 

The ccmn_init routine initializes the XPT and the unit table lock structure. The 
first time the ccmn_init routine is called, it calls the xpt_init routine to request 
the XPT to initialize the CAM subsystem. 

3.3.1.2 The ccmn_open_unit Routine 

The ccmn_open_unit routine handles the common open for all SCSI/CAM 
peripheral device drivers. It must be called for each open before any SCSI device¬ 
specific open code is executed. 

On the first call to the ccmn_open_unit routine for a device, the 
ccmn_gdev_ccb_bld routine is called to issue a GET DEVICE TYPE CCB to 
obtain the Inquiry data. The ccmn_open_unit routine allocates the Peripheral 
Device Structure, PDRV_DEVICE, and a device-specific structure, either 
TAPE_SPECIFIC or DISK_SPECIFIC, based on the device size argument passed. 
The routine also searches the cam_devdesc_tab to obtain a pointer to the Device 
Descriptor Structure for the SCSI device and increments the open count. The 
statically allocated pdrv_unit_table structure contains a pointer to the 
PDRV_DEVICE structure. The PDRV_DEVICE structure contains pointers to the 
DEV_DESC structure and to the device-specific structure. 

3.3.1.3 The ccmn_close_unit Routine 

The ccmn close unit routine handles the common close for all SCSI/CAM 
peripheral device drivers. It sets the open count to zero. 

3.3.2 Common Queue Manipulation Routines 

This section describes the common SCSI/CAM peripheral device driver queue 
manipulation routines. Table 3-5 lists the name of each routine and gives a summary 
description of its function. The sections that follow contain a more detailed 
description of each routine. 
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Table 3-5: Common Queue Manipulation Routines 


Routine 

Summary Description 

ccmn_send_ccb 

sends CCBs to the XPT layer by calling the xpt action 
routine 

ccmn_rem_ccb 

removes a SCSI I/O CCB request from the SCSI/CAM 
peripheral driver active queue and starts a tagged request if a 
tagged CCB is pending 

ccmn_abort_que 

sends an ABORT CCB request for each SCSI I/O CCB on 
the active queue 

ccmn_term_que 

sends a TERMINATE I/O CCB request for each SCSI I/O 
CCB on the active queue 


3.3.2.1 The ccmn_send_ccb Routine 

The ccmn send ccb routine sends CCBs to the XPT layer by calling the 
xpt_action routine. This routine must be called with the Peripheral Device 
Structure locked. 

For SCSI I/O CCBs that are not retries, the request is placed on the active queue. If 
the CCB is a tagged request and the tag queue size for the device has been reached, 
the request is placed on the tagged pending queue so that the request can be sent to 
the XPT at a later time. A high-water mark of half the queue depth for the SCSI 
device is used for tagged requests so that other initiators on the SCSI bus will not be 
blocked from using the device. 

3.3.2.2 The ccmn_rem_ccb Routine 

The ccmn_rem_ccb routine removes a SCSI I/O CCB request from the SCSI/CAM 
peripheral driver active queue and starts a tagged request if a tagged CCB is pending. 
If a tagged CCB is pending, the ccmn_rem_ccb routine places the request on the 
active queue and calls the xpt_action routine to start the tagged request. 

3.3.2.3 The ccmn_abort_que Routine 

The ccmn_abort_que routine sends an ABORT CCB request for each SCSI I/O 
CCB on the active queue. This routine must be called with the Peripheral Device 
Structure locked. 

The ccmn_abort_que routine calls the ccmn_abort_ccb_bld routine to 
create an ABORT CCB for the first active CCB on the active queue and send it to 
the XPT. It calls the ccmn send ccb routine to send the ABORT CCB for each of 
the other CCBs on the active queue that are marked as active to the XPT. The 
ccmn_abort_que routine then calls the ccmn_rel_ccb routine to return the 
ABORT CCB to the XPT. 

3.3.2.4 The ccmn_term_que Routine 

The ccmn_term_que routine sends a TERMINATE I/O CCB request for each 
SCSI I/O CCB on the active queue. This routine must be called with the Peripheral 
Device Structure locked. 
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The ccmn_term_que routine calls the ccmn_term_ccb_bld routine to create a 
TERMINATE I/O CCB for the first active CCB on the active queue and send it to 
the XPT. It calls the ccmn_send_ccb routine to send the TERMINATE I/O CCB 
for each of the other CCBs on the active queue that are marked as active to the XPT. 
The ccmn_term_que routine then calls the ccmn_rel_ccb routine to return the 
TERMINATE I/O CCB to the XPT. 

3.3.3 Common CCB Management Routines 

This section describes the common SCSI/CAM peripheral device driver CCB 
allocation, build, and deallocation routines. Table 3-6 lists the name of each routine 
and gives a summary description of its function. The sections that follow contain a 
more detailed description of each routine. 

Table 3-6: Common CCB Management Routines 


Routine Summary Description 


ccmn_get_ccb 

ccmn_rel_ccb 

ccmn_io_ccb_bId 
ccmn_gdev_ccb_bld 
ccmn_sdev_ccb_bld 
ccmn_sasy_ccb_bld 

ccmn_rsq_ccb_bld 

ccmn_pinq_ccb_bld 
ccmn_abort_ccb_bld 
ccmn_teriri_ccb_bld 
ccmn_bdr_ccb_b1d 

ccmn br ccb bid 


allocates a CCB and fills in the common portion of the CCB 
header 

releases a CCB and returns the sense data buffer for SCSI I/O 
CCBs, if allocated 

allocates a SCSI I/O CCB and fills it in 
creates a GET DEVICE TYPE CCB and sends it to the XPT 
creates a SET DEVICE TYPE CCB and sends it to the XPT 
creates a SET ASYNCHRONOUS CALLBACK CCB and 
sends it to the XPT 

creates a RELEASE SIM QUEUE CCB and sends it to the 
XPT 

creates a PATH INQUIRY CCB and sends it to the XPT 
creates an ABORT CCB and sends it to the XPT 
creates a TERMINATE I/O CCB and sends it to the XPT 
creates a BUS DEVICE RESET CCB and sends it to the 
XPT 

creates a BUS RESET CCB and sends it to the XPT 


3.3.3.1 The ccmn_get_ccb Routine 

The ccmn_get_ccb routine allocates a CCB and fills in the common portion of the 
CCB header. The routine calls the xpt_ccb_alloc routine to allocate a CCB 
structure. The ccmn_get_ccb routine fills in the common portion of the CCB 
header and returns a pointer to that CCB_HEADER. 

3.3.3.2 The ccmn_rel_ccb Routine 

The ccmn_rel_ccb routine releases a CCB and returns the sense data buffer for 
SCSI I/O CCBs, if allocated. The routine calls the xpt_ccb_f ree routine to 
release a CCB structure. For SCSI I/O CCBs, if the sense data length is greater than 
the default sense data length, the ccmn_rel_ccb routine calls the 
ccmn_rel_dbuf routine to return the sense data buffer to the data buffer pool. 
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3.3.3.3 The ccmnJo_ccb_bld Routine 

The ccmn io ccb bld routine allocates a SCSI I/O CCB and fills it in. The 
routine calls the ccmn_get_ccb routine to obtain a CCB structure with the header 
portion filled in. The ccmn_io_ccb_bld routine fills in the SCSI I/O-specific 
fields from the parameters passed and checks the length of the sense data to see if it 
exceeds the length of the reserved sense buffer. If it does, a sense buffer is allocated 
using the ccmn_get_dbuf routine. 

3.3.3.4 The ccmn_gdev_ccb_bld Routine 

The ccmn gdev ccb bld routine creates a GET DEVICE TYPE CCB and sends 
it to the XPT. The routine calls the ccmn_get_ccb routine to allocate a CCB 
structure and fill in the common portion of the CCB header. The 
ccmn_gdev_ccb_bld routine calls the ccmn_send_ccb routine to send the 
CCB structure to the XPT. The request is carried out immediately, so it is not placed 
on the device driver’s active queue. 

3.3.3.5 The ccmn_sdev_ccb_bid Routine 

The ccmn_sdev_ccb_bld routine creates a SET DEVICE TYPE CCB and sends 
it to the XPT. The routine calls the ccmn_get_ccb routine to allocate a CCB 
structure and fill in the common portion of the CCB header. The routine fills in the 
device type field of the CCB and calls the ccmn_send_ccb routine to send the 
CCB structure to the XPT. The request is carried out immediately, so it is not placed 
on the device driver’s active queue. 

3.3.3.6 The ccmn_sasy_ccb_bld Routine 

The ccmn_sasy_ccb bid routine creates a SET ASYNCHRONOUS 
CALLBACK CCB and sends it to the XPT. The routine calls the ccmn_get_ccb 
routine to allocate a CCB structure and fill in the common portion of the CCB 
header. The routine fills in the asynchronous fields of the CCB and calls the 
ccmn_send_ccb routine to send the CCB structure to the XPT. The request is 
carried out immediately, so it is not placed on the device driver’s active queue. 

3.3.3.7 The ccmn_rsq_ccb_bld Routine 

The ccmn rsq ccb bld routine creates a RELEASE SIM QUEUE CCB and 
sends it to the XPT. The routine calls the ccmn_get_ccb routine to allocate a 
CCB structure and fill in the common portion of the CCB header. The routine calls 
the ccmn send ccb routine to send the CCB structure to the XPT. The request is 
carried out immediately, so it is not placed on the device driver’s active queue. 

3.3.3.8 The ccmn_plnq_ccb_bld Routine 

The ccmn_pinq_ccb_bld routine creates a PATH INQUIRY CCB and sends it to 
the XPT. The routine calls the ccmn_get_ccb routine to allocate a CCB structure 
and fill in the common portion of the CCB header. The routine calls the 
ccmn_send_ccb routine to send the CCB structure to the XPT. The request is 
carried out immediately, so it is not placed on the device driver’s active queue. 
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3.3.3.9 The ccmn_abort_ccb_bld Routine 

The ccmn_abort_ccb_bld routine creates an ABORT CCB and sends it to the 
XPT. The routine calls the ccmn_get_ccb routine to allocate a CCB structure and 
fill in the common portion of the CCB header. The routine fills in the address of the 
CCB to be aborted and calls the ccmn_send_ccb routine to send the CCB 
structure to the XPT. The request is carried out immediately, so it is not placed on 
the device driver’s active queue. 

3.3.3.10 The ccmn_term_ccb_bld Routine 

The ccmn_term_ccb_bld routine creates a TERMINATE I/O CCB and sends it 
to the XPT. The routine calls the ccmn_get_ccb routine to allocate a CCB 
structure and fill in the common portion of the CCB header. The routine fills in the 
CCB to be terminated and calls the ccmn_send_ccb routine to send the CCB 
structure to the XPT. The request is carried out immediately, so it is not placed on 
the device driver’s active queue. 

3.3.3.11 The ccmn_bdr_ccbj>ld Routine 

The ccmn_bdr_ccb_bld routine creates a BUS DEVICE RESET CCB and sends 
it to the XPT. The routine calls the ccmn_get_ccb routine to allocate a CCB 
structure and fill in the common portion of the CCB header. The routine calls the 
ccmn_send_ccb routine to send the CCB structure to the XPT. The request is 
carried out immediately, so it is not placed on the device driver’s active queue. 

3.3.3.12 The ccmn_br_ccb_bld Routine 

The ccmn_br_ccb_bld routine creates a BUS RESET CCB and sends it to the 
XPT. The routine calls the ccmn_get_ccb routine to allocate a CCB structure and 
fill in the common portion of the CCB header. The routine calls the 
ccmn_send_ccb routine to send the CCB structure to the XPT. The request is 
carried out immediately, so it is not placed on the device driver’s active queue. 


3.3.4 Common SCSI I/O Command Building Routines 

This section describes the common SCSI/CAM peripheral device driver SCSI I/O 
command build and send routines. Table 3-7 lists the name of the routine and gives 
a summary description of its function. The sections that follow contain a more 
detailed description of each routine. 


Table 3-7: Common SCSI I/O Command Building Routines 


Routine 

Summary Description 

ccmn_tur 

creates a SCSI I/O CCB for the TEST UNIT READY 
command and sends it to the XPT for processing 

ccann_start_unit 

creates a SCSI I/O CCB for the START UNIT command and 
sends it to the XPT for processing 

ccmn_mode_select 

creates a SCSI VO CCB for the MODE SELECT command 
and sends it to the XPT for processing 
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3.3.4.1 The ccmn_tur Routine 

The ccmn tur routine creates a SCSI I/O CCB for the TEST UNIT READY 
command and sends it to the XPT for processing. This routine may be called from 
interrupt context since it will not wait (sleep) for the command to complete. 

The ccmn tur routine calls the ccmn_io_ccb_bld routine to obtain a SCSI I/O 
CCB structure. The ccmn tur routine calls the ccmn_send_ccb routine to send 
the SCSI I/O CCB to the XPT. 

3.3.4.2 The ccmn_start_unit Routine 

The ccmn start unit routine creates a SCSI I/O CCB for the START UNIT 
command and sends it to the XPT for processing. This routine may be called from 
interrupt context since it will not wait (sleep) for the command to complete. 

The ccmn_start_unit routine calls the ccmn_io_ccb_bld routine to obtain a 
SCSI I/O CCB structure. The ccmn_start_unit routine calls the 
ccmn_send_ccb routine to send the SCSI I/O CCB to the XPT. 

3.3.4.3 The ccmn_mode_select Routine 

The ccmn_mode_select routine creates a SCSI I/O CCB for the MODE SELECT 
command and sends it to the XPT for processing. This routine may be called from 
interrupt context since it will not wait (sleep) for the command to complete. The 
routine calls the ccmn_io_ccb_bld routine to obtain a SCSI I/O CCB structure, t 
It uses the msjndex parameter to index into the Mode Select Table pointed to by the 
dd_modsel_tbl member of the Device Descriptor Structure for the SCSI device. 
The ccmn_mode_select routine calls the ccmn_send_ccb routine to send the 
SCSI I/O CCB to the XPT. 

3.3.5 Common CCB Status Routine 

This section describes the common SCSI/CAM peripheral device driver CCB status 
routine. The ccmn_ccb_status routine assigns individual CAM status values to 
generic categories. The following table shows the returned category for each CAM 
status value: 


CAM Status Assigned Category 


CAM_REQ__INPROG 

CAM_REQ_CMP 

CAM_REQ_ABORTED 

CAM_UA_ABORT 

CAM_REQ_CMP_ERR 

CAMJBUSY 

CAM_REQ_INVALID 

CAM_PATH_INVALID 

CAM_DEV_NOT_TH E RE 

CAM_UA_TERMIO 

CAM_SEL_TIMEOUT 

CAM_CMD_TIMEOUT 

CAM_MSG_REJECT_REC 

CAM_SCSI_BUS_RESET 

CAM_UNCOR_PARITY 

CAM_AUTOSENSE_FAIL 

CAM NO HBA 


CATJNPROG 

CAT.CMP 

CAT_ABORT 

CAT.ABORT 

CAT_CMP_ERR 

CAT.BUSY 

CATCCB.ERR 

CAT_NO_DEVICE 

CAT_NO_DEVICE 

CAT.ABORT 

CAT_DEVICE_ERR 

CATJDEVICE.ERR 

CAT_DEVICE_ERR 

CATJRESET 

CAT_DEVICE_ERR 

CAT_B AD_AUTO 

CAT_NO_DEVICE 


USCA Common Modules 3-13 


CAM Status Assigned Category 


CAM_DATA_RUN_ERR 

CAM_UNEXP_BUSFREE 

CAM_S EQU ENC E_FAIL 

CAM_CCB_LEN_ERR 

CAM_PROVIDE_FAIL 

CAM_BDR_SENT 

CAM_REQ_T E RMIO 

CAM_LUN_INVALID 

CAM_TID_INVALID 

CAM_FUNC_NOTAVAIL 

CAM_NO_NEXUS 

CAM_IID_INVALID 

CAM_SCSI_BUSY 

Other 


CAT_DEVICE_ERR 

cat_device_err 

CAT_DEVICE_ERR 

CAT_CCB_ERR 

CAT_CCB_ERR 

CAT_RESET 

CAT_ABORT 

CAT_NO_DEVICE 

CAT_NO_DEVICE 

CAT_CCB_ERR 

CAT_NO_DEVICE 

CAT_NO_DEVICE 

CAT_SCSI_BUSY 

CATJJNKNOWN 


3.3.6 Common Buf Structure Pool Management Routines 

This section describes the common SCSI/CAM peripheral device driver buf 
structure pool allocation and deallocation routines. 

3.3.6.1 The ccmn_get_bp Routine 

The ccmn_get_bp routine allocates a buf structure. This function must not be 
called at interrupt context. The function may sleep waiting for resources. 

3.3.6.2 The ccmn_rei_bp Routine 

The ccmn_rel_bp routine deallocates a buf structure. 

3.3.7 Common Data Buffer Pool Management Routines 

This section describes the common SCSI/CAM peripheral device driver data buffer 
pool allocation and deallocation routines. 

3.3.7.1 The ccmn_get_dbuf Routine 

The ccmn_get_dbuf routine allocates a data buffer area of the size specified by 
calling the kernel memory allocation routines . 

3.3.7.2 The ccmn_rel_dbuf Routine 

The ccmn_rel_dbuf routine deallocates a data buffer. 

3.3.8 Miscellaneous Common Routines 

This section describes the common SCSI/CAM peripheral device driver routines that 
perform miscellaneous operations. Table 3-8 lists the name of each routine and gives 
a summary description of its function. 
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Table 3-8: Miscellaneous Common Routines 


Routine 

Summary Description 

ccmn_ccbwait 

sleeps waiting for a SCSI I/O CCB request to complete 

ccmn_DoSpecialCmd 

provides a simplified interface to the special command 
routine 

ccann_Sy s Spec i a lCmd 

lets a system request issue SCSI I/O commands to the 
SCSI/CAM special I/O interface 

ccmn_errlog 

reports error conditions for the SCSI/CAM peripheral device 
driver 


3.3.8.1 The ccmn_ccbwait Routine 

The ccmn_ccbwait routine sleeps waiting for a SCSI I/O CCB request to 
complete. If the priority is greater than PZERO, the ccmn_ccbwait routine sleeps 
at an interruptible priority in order to catch signals. 

3.3.8.2 The ccmn_DoSpecialCmd Routine 

The ccmn_DoSpecialCmd routine provides a simplified interface to the special 
command routine. The routine prepares for and issues special commands. 

3.3.8.3 The ccmn_SysSpecialCmd Routine 

The ccmn_SysSpecialCmd routine lets a system request issue SCSI I/O 
commands to the SCSI/CAM special I/O interface. This permits existing SCSI 
commands to be issued from within kernel code. 

3.3.8.4 The ccmn_errlog Routine 

The ccmn_errlog routine reports error conditions for the SCSI/CAM peripheral 
device driver. The routine is passed a pointer to the name of the function in which 
the error was detected. The routine builds informational strings based on the error 
condition. 
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USCA Generic Modules 


4 


This chapter describes the generic data structures and routines provided by Digital for 
SCSI/CAM peripheral device driver writers. The generic data structures and routines 
can be used as templates for SCSI/CAM peripheral device drivers to interface with 
the CAM subsystem to perform standard I/O operations. See Chapter 12 for a 
description of the SCSI/CAM special I/O interface, which processes special I/O 
control commands that are not issued to the device through the standard driver entry 
points. 

The generic routines use the common SCSI/CAM peripheral device driver routines 
described in Chapter 3. Using the common and generic routines helps ensure that 
SCSI/CAM peripheral device drivers are consistent with the ULTRIX SCSI/CAM 
Architecture. See Chapter 11 if you plan to define your own SCSI/CAM peripheral 
device drivers. 

4.1 Prerequisites for Using the CAM Generic Routines 

The generic device driver routines use the common routines and data structures 
supplied by Digital. See Chapter 3 for information about how to use the common 
data structures and routines. 

The following routines must be called with the Peripheral Device Structure locked: 

• ccmn_send_ccb 

• ccmn_abort_que 

• ccmn_term_que 


4.1.1 loctl Commands 

The writer of a generic SCSI/CAM peripheral device driver has two options for 
implementing ioctl commands within the driver: 

• Use the ioctl commands that are already defined in /usr/sys/h/ioctl. h 
and implement those that are appropriate for the type of device. 

• Create new ioctl definitions by modifying the /usr/sys/h/ioctl. h file 
to reflect the new ioctl definitions and to implement the new ioctl 
commands within the driver. See the Guide to Writing and Porting VMEbus and 
TURBOchannel Device Drivers for more information. 

It is possible that conflicts with future releases of the operating system may result 
when new ioctl commands are implemented. 

See Chapter 12 for information about the SCSI/CAM special I/O interface to handle 
SCSI special I/O commands. 




4.1.2 Error Handling 

The writer of the device driver is responsible for all error handling within the driver 
and for notifying the user process of the error. 

4.1.3 Kernel Interface 

The kernel entry points for any device driver are defined for both character and block 
devices in the structures cdevsw and bdevsw defined in the 
/usr/sys/h/conf. h file. The kernel entry points are implemented in the 
cdevsw and bdevsw switch tables in the 

/usr/sys/machine/common/conf . c file. If the device driver does not 
implement a specific kernel entry point, then the corresponding entries in the 
cdevsw and bdevsw switch tables must be null. See the Guide to Writing and 
Porting VMEbus and TURBOchannel Device Drivers for more information. 


4.2 Data Structures Used by Generic Routines 

This section describes the generic data structures programmers adapt when they write 
their own SCSI/CAM peripheral device drivers. The following data structures are 
described: 

• CGEN_SPECIFIC, the Generic-Specific Structure 

• CGEN_ACTION, the Generic Action Structure 

4.2.1 The Generic-Specific Structure 

A SCSI/CAM peripheral device structure, CGEN_SPECIFIC, is defined for the 
device controlled by the driver. The CGEN_SPECIFIC structure is defined as 
follows: 

typedef generic_specific struct { 

u_long gen_flags; /* flags - EOM, write locked */ 

u_long gen_state_flags;/* STATE - UNIT_ATTEN, RESET etc. */ 
u__long gen_resid; /* Last operation residual count */ 

}CGEN_SPECIFIC; 

4.2.1.1 The gen_flags Member 

The gen f lags member is used to indicate certain conditions of the SCSI unit. 

The possible flags are: 


Flag Name 


Description 


CGEN_EOM 

CGEN_OFFLINE 

CGEN_WRT_PROT 
CGEN SOFTERR 


The unit is positioned at the end of media. 

The device is returning DEVICE NOT READY in 
response to a command. The media is either not 
loaded or is being loaded. 

The unit is either write protected or is opened read 
only. 

A soft error has been reported by the SCSI unit. 
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Flag Name 

Description 

CGEN_HARDERR 

A hard error has been reported by the SCSI unit. It 
can be reported either through an ioctl or by 
marking the buf structure as EIO. 


4.2.1.2 The gen_state_flags Member 


The gen_state_f lags member is used to indicate certain states of the driver and 
of the SCSI unit. The possible flags are: 


Flag Name 

Description 

CGEN_NOT_READY_STATE 

The unit was opened with the FNDELAY flag and 
the unit had a failure during the open, but was seen. 

CGEN_UNIT_ATTEN_STATE 

A check condition occurred and the sense key was 
UNIT ATTENTION. This usually indicates that a 
media change has occurred, but it could indicate 
power up or reset. Either way, current settings are 
lost 

CGEN_RESET_STATE 

Indicates notification of a reset condition on the 
device or bus. 

CGEN_RESET_PENDING_STATE 

A reset is pending. 

CGEN_OPENED_STATE 

The unit is opened. 


4.2.1.3 The gen_resid Member 

The gen_resid member contains the residual byte count from the last operation. 

4.2.2 The Generic Action Structure 

The SCSI/CAM peripheral device structure, CGEN_ACTION, is passed to the 
generic driver’s action routines to be filled in according to the success or failure of 
the command. The CGEN_ACTION structure is defined as follows: 

typedef struct generic_action { 


CCB_SCSIIO 

*act_ccb; /* 

The 

CCB that is returned to caller */ 

long 

act_ret_error; 

/* 

Error code if any */ 


u_long 

act_fatal; 

/* 

Is this considered fatal? 

V 

u_long 

act_ccb_status; 

/* 

The CCB status code */ 


u_long 

act_scsi_status; 

/* 

The SCSI error code */ 


u_long 

act_chkcond_error; 

/* 

The check condition error 

*/ 


]CGEN_ACTION; 


4.2.2.1 The act_ccb Member 

The act_ccb member is a pointer to the SCSI I/O CCB returned to the calling 
routine. 
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4.2.2.2 The act_ret_error Member 

The act_ret_error contains the error code, if any, returned from the operation. 

4.2.2.3 The actjatal Member 

The act f atal indicates whether an error returned was fatal. The possible flags 
are: 


Flag Name 

Description 

ACT_FAILED 

The action has failed. 

ACT_RESOURCE 

Memory availability problem. 

ACT_PARAMETER 

An invalid parameter was passed. 

ACT_RETRY_EXCEDED 

The maximum retry count for the operation has been 
exceeded. 


4.2.2.4 The act_ccb_status Member 

The act_ccb_status member indicates the CAM generic category code for the 
CCB that was returned from the ccmn_ccb_status routine. 

4.2.2.5 The act_scsi_status Member 

The act_scsi_status member indicates the SCSI status code if the CCB 
completed with an error status. The SCSI status codes are defined in the 
/usr/sys/h/scsi_status. h file. 

4.2.2.6 The act_chkcond_error Member 

The act_chkcond_error member contains the check condition code returned 
from the cgen_ccb_chkcond routine, if the cam_scsi_status member of the 
SCSI I/O CCB is equal to SCSI_STAT_CHECK_CONDITION. The Check 
Condition codes are defined in the /usr/sys/h/cam_generic .h file. 


4.3 Generic I/O Routines 

The generic routines described in this section handle open, close, read, write, and 
other I/O requests from user processes. Table 4-1 lists the name of each routine and 
gives a short description of its function. Descriptions of the routines with syntax 
information, in ULTRIX reference page format, are included in alphabetical order in 
Appendix C. 

Table 4-1: Generic I/O Routines 


Routine 


Summary Description 


cgen_°pen 

cgen_close 


called by the kernel when a user process requests an open of 
the device 
closes the device 
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Table 4-1: (continued) 


Routine 

Summary Description 

cgen_read 

cgen_write 

cgen_strategy 

cgen_ioctl 

handles synchronous read requests for user processes 
handles synchronous write requests for user processes 
handles all I/O requests for user processes 
handles user process requests for specific actions other than 
read, write, open, or close for SCSI tape devices 


4.3.1 The cgen_open Routine 

The cgen_open routine is called by the kernel when a user process requests an 
open of the device. The cgen_open routine calls the ccmn_open_unit routine, 
which manages the SMPJLOCKS and, if passed the exclusive use flag for SCSI 
devices, makes sure that no other process has opened the device. If the 
ccmn_open_unit routine returns success, the necessary data structures are 
allocated. 

The cgen_open routine calls the ccmn_sasy_ccb_bld routine to register for 
asynchronous event notification for the device. The cgen_open routine then enters 
a for loop based on the power-up time specified in the Device Descriptor Structure 
for the device. Within the loop, calls are made to the cgen_ready routine, which 
calls the ccmn_tur routine to issue a TEST UNIT READY command to the device. 

The cgen_open routine calls the ccmn_rel_ccb routine to release the CCB. 

The cgen_open routine checks certain state flags for the device to decide whether 
to send the initial SCSI mode select pages to the device. Depending on the setting of 
the state flags CGEN_UNIT_ATTEN_STATE and CGEN_RESET_STATE, the 
cgen_open routine calls the cgen_open_sel routine for each mode select page 
to be sent to the device. The cgen_open_sel routine fills out the Generic Action 
Structure based on the completion status of the CCB for each mode select page it 
sends. 

4.3.2 The cgen.close Routine 

The cgen_close routine closes the device. The routine checks any device flags 
that are defined to see if action is required, such as rewind on close or release the 
unit. The cgen_close closes the device by calling the ccmn_close_unit 
routine. 

4.3.3 The cgen_read Routine 

The cgen read routine handles synchronous read requests for user processes. It 
passes the user process requests to the cgen_strategy routine. The cgen_read 
routine calls the ccmn_get_bp routine to allocate a buf structure for the user 
process read request. When the I/O is complete, the cgen_read routine calls the 
ccmn_rel_bp routine to deallocate the buf structure. 
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4.3.4 The cgen_write Routine 

The cgen_write routine handles synchronous write requests for user processes. 
The routine passes the user process requests to the cgen_strategy routine. The 
cgen_write routine calls the ccmn_get_bp routine to allocate a buf structure 
for the user process write request. When the I/O is complete, the cgen write 
routine calls the ccmn_rel_bp routine to deallocate the buf structure. 

4.3.5 The cgen_strategy Routine 

The cgen_strategy routine handles all I/O requests for user processes. It 
performs specific checks, depending on whether the request is synchronous or 
asynchronous and on the SCSI device type. The cgen_strategy routine calls the 
ccmn_io__ccb_bld routine to obtain an initialized SCSI I/O CCB and build either 
a read or a write command based on the information contained in the buf structure. 
The cgen_strategy routine then calls the ccmn_send_ccb to place the CCB 
on the active queue and send it to the XPT layer. 

4.3.6 The cgen Joctl Routine 

The cgen_ioctl routine handles user process requests for specific actions other 
than read, write, open, or close for SCSI tape devices. The routine currently issues a 
DEVIOCGET ioctl command for the device, which fills out the devget structure 
passed in, and then calls the cgen_mode_sns routine which issues a 
SCSI_MODE_SENSE to the device to determine the device’s state. The routine then 
calls the ccmn_rel_ccb routine to release the CCB. When the call to 
cgen_mode_sns completes, the cgen_ioctl routine fills out the rest of the 
devget structure based on information contained in the mode sense data. 

4.4 Generic Internal Routines 

The generic routines described in this section are examples that show one method of 
handling errors, events, and conditions. SCSI/CAM peripheral device driver writers 
must implement routines for handling errors, events, and conditions that are 
compatible with the design and the functionality of the specific device. Table 4-2 
lists the name of each routine and gives a short description of its function. 
Descriptions of the routines with syntax information, in ULTRIX reference page 
format, are included in alphabetical order in Appendix C. 

Table 4-2: Generic Internal Routines 


Routine 

Summary Description 

cgen_ccb_chkcond 

cgen_done 

cgen_iodone 

cgen_async 

cgen_minphys 

cgen_slave 

cgen_attach 

decodes the autosense data for a device driver 

the entiy point for all nonread and nonwrite I/O callbacks 

the entry point for all read and write I/O callbacks 

handles notification of asynchronous events 

compares the b bcount with the maximum transfer limit 

for the device 

called at system boot to initialize the lower levels 

called for each bus, target, and LUN after the cgen_slave 

routine returns SUCCESS 
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4.4.1 The cgen_ccb_chkcond Routine 

The cgen_ccb_chkcond routine decodes the autosense data for a device driver 
and returns the appropriate status to the calling routine. The routine is called when a 
SCSI I/O CCB is returned with a CAM status of CAM_REQ_CMP_ERR (request 
completed with error) and a SCSI status of SCSI_STAT_CHECK_CONDITION. The 
routine also sets the appropriate flags in the Generic-Specific Structure. 

4.4.2 The cgen_done Routine 

The cgen done routine is the the entry point for all nonread and nonwrite I/O 
callbacks. The generic device driver uses two callback entry points, one for all 
nonuser I/O requests and one for all user I/O requests. The SCSI/CAM peripheral 
device driver writer can declare multiple callback routines for each type of command 
and can fill the CCB with the address of the appropriate callback routine. 

This is a generic routine for all nonread and nonwrite SCSI I/O CCBs. The SCSI I/O 
CCB should not contain a pointer to a buf structure in the cam_req_map member 
of the structure. If it does, then a wake-up call is issued on the address of the CCB 
and the error is reported. If the SCSI I/O CCB does not contain a pointer to a buf 
structure in the cam_req_map member, then a wake-up call is issued on the address 
of the CCB and the CCB is removed from the active queques. No CCB completion 
status is checked because that is the responsibility of the routine that created the CCB 
and is waiting for completion status. When this routine is entered, context is on the 
interrupt stack and the driver cannot sleep waiting for an event. 

4.4.3 The cgenJodone Routine 

The cgen_iodone routine is the entry point for all read and write I/O callbacks. 
This is a generic routine for all read and write SCSI I/O CCBs. The SCSI I/O CCB 
should contain a pointer to a buf structure in the cam_req_map member of the 
structure. If it does not, then a wake-up call is issued on the address of the CCB and 
the error is reported. If the SCSI I/O CCB does contain a pointer to a buf structure 
in the cam_req_map member, as it should, then the completion status is decoded. 
Depending on the CCB’s completion status, the correct fields within the buf 
structure are filled out. 

The device’s active queues may need to be aborted because of errors or because the 
device is a sequential access device and the transaction was an asynchronous request. 

The CCB is removed from the active queques by a call to the ccmn_rem_ccb 
routine and is released back to the free CCB pool by a call to the ccmn_rel_ccb 
routine. When the cgen_iodone routine is entered, context is on the interrupt 
stack and the driver cannot sleep waiting for an event. 

4.4.4 Thecgen_async Routine 

The cgen async routine handles notification of asynchronous events. The routine 
is called when an Asynchronous Event Notification(AEN), Bus Device Reset (BDR), 
or Bus Reset (BR) occurs. The routine sets the CGEN_RESET_STATE flag and 
clears the CGEN_RESET_PEND_STATE flag for BDRs and bus resets. The routine 
sets the CGEN_UNIT_ATTEN_STATE flag for AENs. 
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4.4.5 The cgen_minphys Routine 

The cgen_minphys routine compares the b_bcount with the maximum transfer 
limit for the device. The routine compares the b_bcount field in the buf structure 
with the maximum transfer limit for the device in the Device Descriptor Structure. 
The count is adjusted if it is greater than the limit. 

4.4.6 The cgen_slave Routine 

The cgen slave routine is called at system boot to initialize the lower levels. The 
routine also checks the bounds for the unit number to ensure it is within the allowed 
range and sets the device-configured bit for the device at the specified bus, target, and 
LUN. 

4.4.7 The cgen_attach Routine 

The cgen attach routine is called for each bus, target, and LUN after the 
cgen_slave routine returns SUCCESS. The routine calls the ccmn open unit 
routine, passing the bus, target, and LUN information. 

The cgen_attach routine calls the ccmn_close_unit routine to close the 
device. If a device of the specified type is found, the device identification string is 
printed. See the Guide to Writing and Porting VMEbus and TURBOchannel Device 
Drivers for more information. 

4.5 Generic Command Support Routines 

The generic routines described in this section are SCSI/CAM command support 
routines. Table 4-3 lists the name of each routine and gives a short description of its 
function. Descriptions of the routines with syntax information, in ULTRIX reference 
page format, are included in alphabetical order in Appendix C. 

Table 4-3: Generic Command Support Routines 


Routine Summary Description 


cgen_ready 

cgen_open_sel 

cgen_mode_sns 


issues a TEST UNIT READY command to the unit defined 

issues a SCSI_MODE_SELECT command to the SCSI 
device 

issues a SCSI_MODE_SENSE command to the unit defined 


4.5.1 The cgen_ready Routine 

The cgen ready routine issues a TEST UNIT READY command to the unit 
defined. The routine calls the ccmn_tur routine to issue the TEST UNIT READY 
command and sleeps waiting for command status. 
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4.5.2 The cgen_open_sel Routine 

The cgen open sel routine issues a SCSI_MODE_SELECT command to the 
SCSI device. The mode select data sent to the device is based on the data contained 
in the Mode Select Table Structure for the device, if one is defined. The 
CGEN_ACTION structure is filled in for the calling routine based on the completion 
status of the CCB. 

The cgen_open_sel routine calls the ccmn_mode_select routine to create a 
SCSI I/O CCB and send it to the XPT for processing. 

4.5.3 The cgen_mode_sns Routine 

The cgen_mode_sns routine issues a SCSI_MODE_SENSE command to the unit 
defined. The CGEN_ACTION structure is filled in for the calling routine based on 
the completion status of the CCB. 
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CAM Data Structures 


Data structures are the mechanism used to pass information between peripheral 
device drivers and the CAM subsystem. This chapter describes the CAM data 
structures used by peripheral device drivers. 

Specifically, the chapter discusses the following: 

• CAM Control Blocks (CCB) 

• Input/Output (I/O) data structures 

• Control CCB structures 

• Configuration data structures 

Other chapters reference these structures. You can read this chapter now to become 
familiar with the structures, or you can refer to it when you encounter references to 
the structures in other chapters. 


5.1 CAM Control Blocks 

The CAM Control Block (CCB) data structures let the device driver writer specify 
the action to be performed by the XPT and SIM. The CCBs are allocated by calling 
the xpt_ccb_alloc routine. 

Table 5-1 contains the name of each CCB data structure and a brief description of its 
purpose. 

Table 5-1: CAM Control Blocks 


CCB Name 

Description 

CCB SCSIIO 

Requests SCSI I/O 

CCB GETDEV 

Gets device type 

CCB PATHINQ 

Sends a path inquiry 

CCB RELSIM 

Releases SIM queue 

CCB SETASYNC 

Sets asynchronous callback 

CCB SETDEV 

Sets device type 

CCB ABORT 

Aborts XPT request 

CCB RESETBUS 

Resets SCSI bus 

CCB RESETDEV 

Resets SCSI device 

CCB TERMIO 

Terminates I/O process request 


All CCBs contain a CCB_HEADER structure. Peripheral device driver writers need 
to understand the CCB_HEADER data structure, which is discussed in the section that 
follows. 







5.1.1 The CCB HEADER Structure 


SCSI/CAM peripheral device driver writers allocate a CCB structure by calling the 
xpt ccb alloc routine. The CCB_HEADER structure is common to all CCBs 
and is the first structure filled in. It contains the following members: 


typedef struct ccb_header 
{ 

struct ccb_header *my_addr; /* 


u_short cam_ccb_len; /* 

uchar cam_func_code; /* 

u_char cam_status; /* 

/* 

u_char cam_path_id; /* 

u_char cam_target_id; /* 

u_char cam_target_lun; /* 

u__long cam_flags; /* 

/* 

} CCB_HEADER; 


The address of this CCB */ 
Length of the entire CCB */ 
XPT function code */ 
Returned CAM subsystem */ 
status */ 

Path ID for the request */ 
Target device ID */ 

Target LUN number */ 

Flags for operation of */ 
the subsystem */ 


5.1.1.1 The my_addr and cam_ccbJen Members 

The my_addr member is set to a pointer to the virtual address of the starting 
address of the CAM Control Block (CCB). It is automatically filled in by the 
xpt_ccb_alloc routine. 

The cam_ccb_len member is set to the length in bytes of this specific CCB type. 
This field is filled in by the ccmn_get_ccb routine. The length includes the 
my_addr and cam_ccb_len members. 

5.1.1.2 The cam_func_code Member 

The cam_f unc_code member lets device-driver writers specify the CCB type 
XPT/SIM functions. Device-driver writers can set this member to one of the function 
codes listed in Table 5-2. 

Table 5-2: CAM Function Codes 


Function Code 

Meaning 

XPT_NOOP 

Do not execute anything in the XPT/SIM. 

XPT_SCSI_IO 

Execute the requested SCSI I/O. Specify the details of the 
SCSI I/O by setting the appropriate members of the 

CCB SCSIIO structure. 

XPT_GDEV_TYPE 

Get the device type information. Obtain this information by 
referencing the CCB_GETDEV structure. 

XPT_PATH_INQ 

Get the path inquiry information. Obtain this information by 
referencing the CCB_pathinq structure. 

XPT_REL_SIMQ 

Release the SIM queue that is frozen. 

XPT_ASYNC_CB 

Set the asynchronous callback parameters. Obtain 
asynchronous callback information from the 

CCB_S ETASYNC structure. 

XPT_SDEV_TYPE 

Set the device type information. Obtain the device type 
information from the CCB SETDEV structure. 
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Table 5-2: (continued) 


Function Code 

Meaning 

XPT_ABORT 

Abort the specified CCB. Specify the abort to the CCB by 
setting the appropriate member of the CCB_abort 
structure. 

XPT_RESET_BUS 

Reset the SCSI bus. 

XPT_RESET_DEV 

Reset the SCSI device. 

XPT_TERM_IO 

Terminate the I/O process. Specify the CCB process to 
terminate by setting the appropriate member of the 
CCB_TERMIO structure. 


5.1.1.3 The cam_status Member 

The cam_status member is the action or event that occurred during this CAM 
Control Block (CCB) request. The cam_status member is set by the XPT/SIM 
after the specified function completes. A CAM_REQ_INPROG status indicates that 
either the function is still executing or is still in the queue. The XPT/SIM can set this 
member to one of the CAM status codes listed in Table 5-3 

Table 5-3: CAM Status Codes 


CAM Status Code Meaning 


CAM_REQ_INPROG 

CAM_REQ_CMP 

CAM_REQ_ABO RTED 

CAM_REQ_UA_ABORT 

CAM_REQ_CMP_ERR 

CAM_BUSY 

CAM_REQ_INVALID 

CAM_PATH_INVALID 

CAM_DEV_NOT_THE RE 
CAM_UA_TERMIO 

CAM_SEL_TIMEOUT 
CAM_CMD_TIMEOUT 
CAM_MSG_REJECT_REC 
C AM_SC S I__BU S_RE SET 

CAM_UNCOR_PARITY 
CAM_AUTOSENSE_FAIL 
CAM NO HBA 


A CCB request is in progress. 

A CCB request completed without errors. 

A CCB request was aborted by the host processor. 

The SIM was not able to abort the specified CCB. 

The specified CCB request completed with an error. 

The CAM subsystem is busy. The CCB returns to the caller, 
the request must be resubmitted. 

The specified CCB request is not valid. 

The path ID specified in the cam_path_id member of the 
CCB_header structure is not valid. 

The specified SCSI device is not installed at this location. 

The CAM subsystem was unable to terminate the specified 
CCB I/O request. 

A target-selection timeout occurred. 

A command timeout occurred. 

A message rejection was received by the SIM. 

The SCSI bus-reset was issued by the SIM or was seen on 
the bus by the SIM. 

An uncorrectable parity error occurred. 

The autosense request-sense command failed. 

No HBA was detected. 
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Table 5-3: (continued) 


CAM Status Code 

Meaning 

CAM_DATA_RUN_ERR 

A data overflow or underflow error occurred. 

CAM_UNEXP_BUSFREE 

An unexpected bus free was detected. 

CAM_S EQU ENC E_FAIL 

A target bus phase-sequence failure occurred. 

CAM_CCB_LEN_ERR 

The CCB length specified in the cam ccb len member of 
the CCB_HEADER structure is incorrect. 

CAM_PROVIDE_FAIL 

The requested capability could not be provided. 

CAM_BDR_SENT 

A SCSI BDR message was sent to the target. 

CAM_REQ_TERMIO 

The CCB request was terminated by the host. 

CAM_SIM_QFRZN 

The SIM queue is frozen. 

CAM_AUTOSNS_VALID 

Autosense data is valid for target. 


5.2 I/O Data Structure 

Peripheral device drivers make SCSI device action requests through the following 
data structures: 

• The CCB.SCSIIO structure 

• The CDB_UN structure 


5.2.1 The CCB.SCSIIO Structure 

A peripheral driver indicates to the XPT/SIM that it wants to make a SCSI device 
action request by setting the cam_f unc_code member of the CCB_HEADER 
structure to the constant XPT_SCSI_I0. The peripheral-driver writer then uses the 
CCB_SCSII0 structure to specify the requests. 

The CCB_SCSIIO structure contains the following members: 

typedef struct 
t 

CCB_HEADER cam_ch; /* Header information fields */ 
u_char *cam_pdrv_ptr; /* Ptr to the Peripheral driver */ 

/* working set */ 

CCBHEADER *cam_next_ccb; /* Ptr to the next CCB for action */ 
u char *cam_req_map; /* Ptr for mapping info on the Req. */ 
void (*cam_cbfcnp)(); /* Callback on completion function */ 
u_char *cam_data_ptr; /* Pointer to the data buf/SG list */ 
u long cam_dxfer_len; /* Data xfer length */ 

uchar *cam_sense_ptr; /* Pointer to the sense data buffer */ 

u_char cam_sense_len; /* Num of bytes in the Autosense buf */ 
u_char cam_cdb_len; /* Number of bytes for the CDB */ 
u_short cam_sglist_cnt; /* Num of scatter/gather list entries */ 

u_long cam_osd_rsvdO; /* OSD Reserved field, for alignment */ 
long cam_resid; /* Transfer residual length: 2's comp */ 

CDB_UN cam_cdb_io; /* Union for CDB bytes/pointer */ 
u_long cam_timeout; /* Timeout value */ 
u_char *cam_msg_ptr; /* Pointer to the message buffer */ 

u_short cam_msgb_len; /* Num of bytes in the message buf */ 
u_short cam_vu_flags; /* Vendor unique flags */ 
u_char cam_tag_action; /* What to do for tag queuing */ 
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u_char cam_iorsvdO[3]; /* Reserved field, for alignment */ 

u_char cam_sim_priv[ SIM_PRIV ] ; /* SIM private data area */ 

} CCB_SCSIIO; 


5.2.2 The CDB_UN Structure 

The CDB_UN structure contains: 

typedef union 
{ 

u_char *cam_cdb_ptr; /* Pointer to the CDB bytes to send */ 

u_char camcdbbytes[ IOCDBLEN ]; /* Area for the inline CDB to send */ 

J CDBJJN; 


5.3 Control CCB Structures 

The control CCB structures allow the driver writer to specify such tasks as resetting 
the SCSI bus, terminating an I/O process request, and so forth. This section discusses 
the following control structures: 

• CCB_RELSIM 

• CCB_SETASYNC 

• CCB_ ABORT 

• CCB_RES ETB U S 

• CCB.RESETDEV 

• CCB_TERMIO 

These structures are discussed in the sections that follow. 

5.3.1 The CCB.RELSIM Structure 

Device-driver writers use the CCB_RELSIM structure to release the SIM’s internal 
CCB queue. The CCB_RELSIM structure contains: 

typedef struct 
{ 

CCB_HEADER cam_ch; /* Header information fields */ 

} CCB_RELSIM; 


5.3.2 The CCB_SETASYNC Structure 

SCSI/CAM peripheral device driver writers use the CCBJSETASYNC structure to 
set the asynchronous callback for notification of the following events when they 
occur: 

• Unsolicited SCSI BUS DEVICE RESET (BDR) 

• Unsolicited RESELECTION 

• SCSI AEN (asynchronous event notification enabled) 

• Sent BDR to target 

• SIM module loaded 
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• SIM module unloaded 

• New devices found 

The CCB_SETASYNC structure is defined as follows: 

typedef struct 
{ 

CCBHEADER cam_ch; 
u_long cam_async_flags; 
void (*cam_async_func){); 
uchar *pdrv_buf; 

u_char pdrv_buf_len; 

} CCB_SETASYNC; 


5.3.3 The CCB_ABORT Structure 

Device-driver writers use the CCB_ABORT structure to abort a CCB that is on the 
SIM queue. The CCB_ABORT structure contains: 

typedef struct 

{ 

CCB_HEADER cam_ch; 

CCB_HEADER *cam_abort_ch; 

} CCB_ABORT; 


5.3.4 The CCB.RESETBUS Structure 

Device-driver writers use the CCB_RESETBUS structure to reset the SCSI bus. The 
CCB_RESETBUS structure is defined as follows: 

typedef struct 

{ 

CCB_HEADER cam_ch; /* Header information fields */ 

} CCB_RESETBUS; 

5.3.5 The CCB_RESETDEV Structure 

Device-driver writers use the CCB_RESETDEV structure to reset a single SCSI 
device. The CCB_resetdev structure is defined as follows: 

typedef struct 

{ 

CCBHEADER cam_ch; /* Header information fields */ 

} CCB_RESETDEV; 

5.3.6 The CCB JTERMIO Structure 

Device-driver writers use the CCB_TERMIO structure to terminate an I/O process 
request. The CCB_TERMIO structure is defined as follows: 

typedef struct 
{ 

CCB_HEADER cam_ch; 

CCB_HEADER *cam_termio_ch; 

} CCB_TERMIO; 


/* Header information fields */ 

/* Pointer to the CCB to terminate */ 


/* Header information fields */ 

/* Pointer to the CCB to abort */ 


/* Header information fields */ 

/* Event enables for Callback response */ 
/* Async Callback function address */ 

/* Buffer set aside by the */ 

/* peripheral driver */ 

/* The size of the buffer */ 
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5.4 Configuration CCB Structures 

The configuration CCB structures let the driver writer obtain information such as the 
device type, version number for the SIM/HBA, and vendor IDS. The following 
configuration CCBs are described in this section: 

• The CCB_GETDEV structure 

• The CDB_SETDEV structure 

• The CDB_PATHINQ structure 

These structures are discussed in the following sections. 

5.4.1 The CCB_GETDEV Structure 

Device-driver writers use the CCB_GETDEV structure to obtain a device type and 
inquiry information. The CCB_GETDEV structure is defined as follows: 

typedef struct 

{ 

CCB_HEADER cam_ch; /* Header information fields */ 

u_char cam_pd_type; /* Peripheral device type from the TLUN */ 

char *cam_inq_data; /* Ptr to the inquiry data space */ 

} CCB_GETDEV; 


5.4.2 The CCB_SETDEV Structure 

Device-driver writers use the CCB_SETDEV structure to set the device type. The 
CCB_S ETDEV structure is defined as follows: 

typedef struct 

{ 

CCB_HEADER cam_ch; /* Header information fields */ 

u_char cam_dev_type; /* Value for the dev type field in EDT */ 

} CCB_SETDEV; 


5.4.3 The CCB_PATHINQ Structure 

Device-driver writers use the CCB_PATHINQ structure to obtain SIM information 
such as supported features and version numbers. The CCB_PATHINQ structure is 
defined as follows: 

typedef struct 

{ 

CCB_HEADER camch; 
u_char cam_version_num; 
u_char cam_hba_inquiry; 
u_char cam_target_sprt; 
u_char camhbamisc; 
u_char cam_vuhba_flags[ VUHBA ]; 
u_long cam_sim_priv; 
u_long cam_async_flags; 
u_char cam_hpath_id; 
u_char cam_initiator_id; 
char cam_sim_vid[ SIM_ID ]; 
char cam_hba_vid[ HBA_ID ]; 
u_char *cam_osd_usage; 

} CCB_PATHINQ; 


/* Header information fields */ 

/* Version number for the SIM/HBA */ 

/* Mimic of INQ byte 7 for the HBA */ 
/* Flags for target mode support */ 

/* Misc HBA feature flags */ 

/* Vendor unique capabilities */ 

/* Size of SIM private data area */ 

/* Event cap. for Async Callback */ 

/* Highest path ID in the subsystem */ 
/* ID of the HBA on the SCSI bus */ 

/* Vendor ID of the SIM */ 

/* Vendor ID of the HBA */ 

/* Ptr for the OSD specific area */ 
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SCSI/CAM Configuration Driver Modules 



This chapter describes the data structures and routines used by the Configuration 
driver to interface with the CAM subsystem. It also describes the 
/usr/sys/io/cam/cam_conf ig. c file, which contains SCSI/CAM peripheral 
device driver configuration information. SCSI/CAM peripheral device driver writers 
add to this file external declarations and entries to the SCSI/CAM peripheral driver 
configuration table for their peripheral device drivers. 

6.1 Configuration Driver Introduction 

The Configuration driver dynamically initializes the XPT and SIM layers of the 
CAM subsystem, at run time. This enables support for a generic kernel that is 
configured for all processors and all CAM subsystem software, for example, all HBA 
drivers. After initialization is complete, the Configuration driver scans the SCSI bus 
and stores INQUIRY information about each SCSI device detected. 

Once the CAM subsystem is initialized and the scanning information stored, the 
SCSI/CAM peripheral device drivers can use the subsystem. They can determine 
what devices have been detected and allocate memory appropriately. They can also 
request resources from the XPT layer using the XPT_GDEV_TYPE and 
XPT_SDEV_TYPE get and set device information CCBs. 

The Configuration driver module logically exists in the SCSI/CAM peripheral device 
driver layer above the XPT. 

6.2 Configuration Driver XPT Interface 

The Configuration driver is responsible for supporting the following XPT routines: 

• GET DEVICE TYPE CCB 

• SET DEVICE TYPE CCB 

• SET ASYNCHRONOUS CALLBACK CCB 

The Configuration driver also supports the configuration and bus scanning for loaded 
SIM modules. 


6.3 Configuration Driver Data Structures 

This section describes the following Configuration driver data structures: 

• CCFG_CTRL - The Configuration driver control structure 

• EDT - The CAM equipment device table 

• CAM_PERIPHERAL_DRIVER - The SCSI/CAM peripheral driver configuration 
structure 



6.3.1 The Configuration driver control structure 

The Configuration driver control structure, CCFG_CTRL, contains flags used by the 
Configuration driver for the scanning process. It also sets aside an area to contain the 
data returned from the INQUIRY CCBs during the initial scanning process. The 
structure is defined as follows: 

typedef struct ccfg_ctrl 
{ 

u_long ccfg_flags; 

ALL_INQ_DATA inqbuf; 
struct lock_t c_lk_ctrl; 

} CCFG_CTRL; 


6.3.1.1 The ccfgjlags Member 

The ccfg_flags member contains the flags used by the Configuration driver to 
control operations. The possible settings are as follows: 

• EDTJNSCAN - Which signals that an EDT scan is in progress 

• INQJNPROG - Which indicates that an INQUIRY CCB is in progress 

6.3.1.2 The lnq_buf Member 

The inq_buf member sets aside a working or temporary area to hold the returned 
data described in the standard INQUIRY structure, ALL_INQ_DATA, which is 
defined in the file /usr/sys/h/scsi_all. h. 

6.3.2 The CAM Equipment Device Table 

The Configuration driver works with the XPT to allocate, initialize, and maintain the 
CAM equipment device table structure, EDT. An EDT structure is allocated for each 
SCSI bus. The structure is an 8x8-element array that contains device inquiry 
information, asynchronous callback flags, and a signal flag if a device was found, 
based on the number of targets and the number of LUNs on the SCSI bus. The 
structure is defined as follows: 

typedef struct edt 
{ 

CAM_EDT_ENTRY edt[ NDPS ][ NLPT ]; 
u_long edt_flags; 
u_long edt_scan_count; 
struct lock_t c_lk_edt 
] EDT; 


6.3.2.1 The edt Member 

The edt member is a structure of the type CAMJEDT_ENTRY, which is defined in 
the /usr/sys/h/cam. h file. Each CAM_EDTJENTRY structure is an entry in 
the CAM equipment device table containing the SCSI ID and LUN for each device 
on the SCSI bus. The array dimensions are the number of devices per SCSI bus 
(NDPS) and the number of LUNs per target (NLPT). The structure and constants are 
defined in the /usr/sys/h/dec_cam. h file. 


/* a layer for targets/LUNs */ 
/* flags for EDT access */ 

/* # of XPT ASYNC CB readers */ 
/* for locking per bus */ 


/* controlling flags */ 

/* scratch area for the INQUIRY data */ 
/* for locking on the control struct */ 
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6.3.2.2 The edt_scan_count Member 

The edt_scan_count member contains the number of processes reading the EDT 
structure. 

6.3.2.3 The edt_flags Member 

The edt_f lags member sets the flags for controlling access to the CAM 
equipment device table. 


6.3.3 The SCSI/CAM Peripheral Driver Configuration Structure 

CAM_PERIPHERAL_DRIVER, the SCSI/CAM peripheral driver configuration 
structure, contains the name of the device and defines the routines that are accessed 
as part of the system configuration process. The structure is defined as follows: 

typedef struct cam_peripheral_driver 
{ 

char *cpd_name; 

int (*cpd_slave)(); 

int (*cpd_attach)(); 

int (*cpd_unload)(); 

] CAM_PERIPHERAL_DRIVER; 


6.3.3.1 The cpd.name Member 

The cpd_name member is a pointer to the device name contained in the 
ui_devname member of the kernel data structure, uba_device. See the Guide 
to Writing and Porting VMEbus and TURBOchannel Device Drivers for more 
information. 

6.3.3.2 The cpd_slave Member 

The cpd_slave member is a function pointer to the SCSI/CAM peripheral device 
driver slave routine, which finds the device attached to the SCSI bus controller. 

6.3.3.3 The cpd_attach Member 

The cpd_attach member is a function pointer to the SCSI/CAM peripheral device 
driver attach routine, which attaches the device to the controller and initializes the 
driver fields for the device. 

6.3.3.4 The cpd_unload Member 

Not implemented. 

6.4 The cam_config.c File 

The Configuration driver file, /usr/sys/io/cam/cam_conf ig. c, contains 
SCSI/CAM peripheral device driver configuraton information. SCSI/CAM peripheral 
device driver writers edit the file, as the superuser, to add extern declarations for 
their hardware devices and to add entries for the devices to the SCSI/CAM peripheral 
driver configuration table. 

The section of the file where the extern declarations are added looks like the 
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following: 

extern int crzslave(), crzattach(); 
extern int ctzslave(), ctzattach(); 
extern int cczslave(), cczattach(); 


/* Disk Driver */ 

/* Tape Driver */ 

/* CD-ROM Driver */ 


/* VENDOR: Add the extern declarations for your hardware following this 
comment line. */ 


A sample declaration for third-party SCSI/CAM peripheral device driver might be as 
follows: 

extern int toastslave(), toastattach(); /* Non-tape or -disk Driver */ 


The section of the file where the SCSI/CAM peripheral driver configuration table 
entries are added looks like the following: 


/* 

* CAM Peripheral Driver Configuration Table. 

V 

struct cam_peripheral_driver cam_peripheral_drivers[] = { 
{ "crz", crzslave, crzattach }, 

{ "ctz", ctzslave, ctzattach }, 

{ "ccz", cczslave, cczattach ] 


/* VENDOR: Add your hardware entries following this comment line. */ 
J; 

When you add your entry, be sure to place a comma (,) after the last member in the 
structure supplied by Digital. A sample entry for third-party hardware might be as 
follows: 

{ "ccz", cczslave, cczattach }, 

/* VENDOR: Add your hardware entries following this comment line. */ 

{ "wheat", toastslave, toastattach}, /* Non-tape or -disk Driver */ 

}; 


6.5 Configuration Driver Entry Point Routines 

The following Configuration driver routines are entry point routines that are 
accessible to the XPT and SIM modules as part of the Configuration driver interface. 
Table 6-1 lists the name of each routine and gives a short description of its function. 
The sections that follow contain a more detailed description of each routine. 
Descriptions of the routines with syntax information, in ULTRIX reference page 
format, are included in alphabetical order in Appendix C. 

Table 6-1: Configuration Driver Entry Point Routines 


Routine Summary Description 


ccf g_slave calls a SCSI/CAM peripheral driver’s slave routine after a 

match on the cpd_name member of the 
CAM_PERIPHERALJDRI VER structure is found 
ccf g_attach calls a SCSI/CAM peripheral driver’s attach routine after a 

match on the cpdjname member of the 
CAM_PER1PHER ALJDRI VER structure is found 
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Table 6-1: (continued) 


Routine 

Summary Description 

ccfg_action 

calls the internal routines that handle any CCB that accesses 
the CAM equipment device table structure 

ccfg_edtscan 

issues SCSI INQUIRY commands to all possible SCSI 
targets and LUNs attached to the buses 


6.5.1 The ccfg_slave Routine 

The ccf g slave routine calls a SCSI/CAM peripheral driver’s slave routine after a 
match on the cpd_name member of the CAM_PERIPHERAL_DRIVER structure is 
found. The routine is called during autoconfiguration. The ccfgslave routine 
locates the configured driver in the SCSI/CAM peripheral driver configuration table. 
If the driver is located successfully, the SCSI/CAM peripheral driver’s slave routine 
is called with a pointer to the unit information structure for the device from the 
kernel uba_device structure and the virtual address of its control and status 
register (CSR). The SCSI/CAM peripheral driver’s slave routine performs its own 
slave initialization. 

6.5.2 The ccfg_attach Routine 

The ccf g_attach routine calls a SCSI/CAM peripheral driver’s attach routine 
after a match on the cpd name member of the CAM_PERIPHERAL_DRIVER 
structure is found. The routine is called during autoconfiguration. The 
ccf g_attach routine locates the configured driver in the SCSI/CAM peripheral 
driver configuration table. If the driver is located successfully, the SCSI/CAM 
peripheral driver’s attach routine is called with a pointer to the unit information 
structure for the device from the kernel uba device structure. The SCSI/CAM 
peripheral driver’s attach routine performs its own attach initialization. 

6.5.3 The ccfg_action Routine 

The ccf g_action routine calls the internal routines that handle any CCB that 
accesses the CAM equipment device table structure. The CAM function codes 
supported are XPT_GDEV_TYPE, XPT_SASYNC_CB, and XPT_SDEV_TYPE. 

6.5.4 The ccfg_edtscan Routine 

The ccf g edtscan routine issues SCSI INQUIRY commands to all possible SCSI 
targets and LUNs attached to the buses. The routine uses the CAM subsystem in the 
normal manner by sending SCSI I/O CCBs to the SIMs. The INQUIRY data 
returned is stored in the EDT structures and the cam tlun f ound flag is set. This 
routine can be called by the SCSI/CAM peripheral device drivers to reissue a full, 
partial, or single bus scan command. 
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CAM XPT I/O Support Routines 


This chapter contains descriptions of the Transport (XPT) layer routines used by 
SCSI/CAM device driver writers. Table 7-1 contains a list of the routines with a 
short description of each. Following the table is a description of each routine. 
Descriptions of the routines with syntax information, in ULTRIX reference page 
format, are included in alphabetical order in Appendix C. 

Table 7-1: XPT I/O Support Routines 


Routine 

Summary Description 

xpt_action 

xpt_ccb_alloc 

xpt_ccb_free 

xpt_init 

calls the appropriate XPT/SIM routine 

allocates a CAM Control Block (CCB) 

frees a previously allocated CCB 

validates the initialized state of the CAM subsystem 


7.1 The xpt_action Routine 

The xpt_action routine calls the appropriate XPT/SIM routine. The routine 
routes the specified CCB to the appropriate SIM module or to the Configuration 
driver, depending on the CCB type and on the path ID specified in the CCB. 
Vendor-unique CCBs are also supported. Those CCBs are passed to the appropriate 
SIM module according to the path ID specified in the CCB. 

7.2 The xpt_ccb_alloc Routine 

The xpt_ccb_alloc routine allocates a CAM Control Block (CCB) for use by a 
SCSI/CAM peripheral device driver. The xpt_ccb_alloc routine returns a pointer 
to a preallocated data buffer large enough to contain any CCB structure. The 
peripheral device driver uses this structure for its XPT/SIM requests. The routine also 
ensures that the SIM private data space and peripheral device driver pointer, 
cam_pdrv_ptr, are set up. 

7.3 The xpt_ccb_free Routine 

The xpt_ccb_f ree routine frees a previously allocated CCB. The routine returns 
a CCB, previously allocated by a peripheral device driver, to the CCB pool. 







7.4 The xptjnit Routine 

The xpt_init routine validates the initialized state of the CAM subsystem. The 
routine initializes all global and internal variables used by the CAM subsystem 
through a call to the Configuration driver. Peripheral device drivers must call this 
routine either during or prior to their own initialization. The xpt init routine 
simply returns to the calling SCSI/CAM peripheral device driver if the CAM 
subsystem was previously initialized. 
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CAM SIM Modules 




This chapter describes how the SIM layers handle asynchronous callbacks. It also 
describes the following SIM routines: 

• sim_action 

• sim_init 

Descriptions of the routines with syntax information, in ULTRIX reference page 
format, are included in alphabetical order in Appendix C. 

8.1 SIM Asynchronous Callback Handling 

This section describes how the SIM layers handle asynchronous callbacks from the 
XPT to SCSI/CAM peripheral device drivers when an event such as a SCSI Bus 
Device Reset (BDR) or an Asynchronous Event Notification (AEN) occurs. 

Each SCSI/CAM peripheral device driver registers an asynchronous callback function 
for each active SCSI device during driver initialization. The SCSI/CAM peripheral 
device drivers use the ccmn_sasy_ccb_bld routine to create a SET 
ASYNCHRONOUS CALLBACK CCB and send it to the XPT. 

The async_f lags field of the CCB are set to 1 for those events of which the 
SCSI/CAM peripheral device driver wants to be notified using the asynchronous 
callback function. The possible async_flags settings are: 


Flag Name 

Description 

AC_FOUND_D EVIC E S 

A new device was found during a rescan. 

AC_SIM_DEREGISTER 

A previously loaded SIM driver has deregistered. 

AC_SIM_REGISTER 

A loaded SIM driver has registered. 

AC_SENT_BDR 

A bus device reset (BDR) message was sent to the 
target. 

AC_SCSI_AEN 

A SCSI Asynchronous Event Notification has been 
received. 

AC_UNSOL_RESEL 

An unsolicited reselection of the system by a device 
on the bus has occurred. 

ACMBU S_RE SET 

A SCSI bus RESET occurred. 






8.2 SIM Routines Used by Device Driver Writers 

This section describes the SIM routines device driver writers need to understand. 

8.2.1 The sim_action Routine 

The sim_action routine initiates an I/O request from a SCSI/CAM peripheral 
device driver. The routine is used by the XPT for immediate as well as for queued 
operations. When the operation completes, the SIM calls back directly to the 
peripheral driver using the CCB callback address, if callbacks are enabled and the 
operation is not to be carried out immediately. 

The SIM determines whether an operation is to be carried out immediately or to be 
queued according to the function code of the CCB structure. All queued operations, 
such as “Execute SCSI I/O’’ (reads or writes), are placed by the SIM on a nexus- 
specific queue and return with a CAM status of CAM_INPROG. 

Some immediate operations, as described in the American National Standard for 
Information Systems, SCSI-2 Common Access Method: Transport and SCSI Interface 
Module, working draft, X3T9.2/90-186, may not be executed immediately. However, 
all CCBs to be carried out immediately return to the XPT layer immediately. For 
example, the ABORT CCB command does not always complete synchronously with 
its call; however, the CCB_ABORT is returned to the XPT immediately. An 
XPT_RESET_BUS CCB returns to the XPT following the reset of the bus. 

8.2.2 The simJnit Routine 

The sim_init routine initializes the SIM. The SIM clears all its queues and 
releases all allocated resources in response to this call. This routine is called using 
the function address contained in the CAM_SIM_ENTRY structure. This routine can 
be called at any time; the SIM layer must ensure that data integrity is maintained. 
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This chapter describes the error-logging macros, data structures, and routines 
provided by Digital for SCSI/CAM peripheral device driver writers. 


9.1 CAM Error Handling Macro 

Digital supplies an error-logging macro, CAM_ERROR, with the USCA software. 
SCSI device driver writers can activate the macro by defining the constant 
CAMERRLOG. Errors are reported using the same error-logging interface to each of 
the modules within the CAM subsystem. 

The macro is defined in the /usr/sys/io/cam/cam_errlog. h file as follows:. 

#if defined(CAMERRLOG) && !defined(lint) 

# define CAM_ERROR( FUNC, MSGSTR, EFLAGS, ARG4, ARG5, ARG6) \ 

t \ 

/* VARARGS */ \ 

(void)(*local_errlog)( FUNC, MSGSTR, EFLAGS, ARG4, ARG5, ARG6 ); \ 

] 

tfelse /* CAMERRLOG and not lint */ 

# define CAM_ERROR( FUNC, MSGSTR, EFLAGS, ARG4, ARG5, ARG6 ) \ 

{ \ 

/* VARARGS */ 
printf( "%s: %s\n", \ 

(((FUNC) != (char *)NULL) ? (FUNC) : "CAM Subsystem" ), \ 
(((MSGSTR) 1= (char *)NULL) ? (MSGSTR) : "Unknown Error" ));\ 

} 

#endif /* CAMERRLOG and not lint */ 

#endif /* _CAM_ERRLOG_ */ 

The arguments to the macro contain different types of information. The first two 
arguments to the macro are strings containing the function name and the message 
string that is sent to the error logger from the function. If the CAMERRLOG macro 
is undefined, the message string is reported to the console. The third argument 
contains error flags for the local error handler. The remaining arguments are local 
parameters defined by the writer of the error-logging routine. 

The CAM_ERROR macro presents a consistant error-logging interface to the 
modules within the CAM subsystem. Using the macro lets all the routines within 
each module that need to report and log error information use the same macro call 
and arguments. Using this macro also keeps each reported error string with the code 
within the module that originally reported the error. 

Individual modules contain their own module-specific error-logging routines. Each 
source file contains a declaration of the pointer to the local error-logging routine as 




follows: 

static void (*local_errorlog)(); 

The macro calls the local error-logging routine through the local pointer. The pointer 
is loaded with the local error-handler address, either within the initiailization code for 
that module or as part of the initialized data. The following example shows the 
address of the sx_errorlog function being loaded to the local error-logging 
variable, local_errlog: 

extern void sxerrorlog(); 

static void (*local_errlog)() = sx_errorlog; 

SCSI/CAM peripheral common modules can declare the local pointer to contain the 
error handler from another SCSI/CAM peripheral common module. 

9.2 CAM Error Logging Structures 

This section describes the following CAM error-logging data structures: 

• CAM_ERR_ENTRY, the Error Entry Structure 

• CAM_ERR_HDR, the Error Header Structure 

The structures are defined in the /usr/sys/h/cam_logger. h file. 

9.2.1 The Error Entry Structure 

The Error Entry Structure, CAM_ERR_ENTRY, describes an entry in the error log 
packet. There can be multiple entries in an error log packet. The structure is defined 
as follows: 

typedef struct cam_err_entry 
u_longent_type; /* 

u_longent_size; /* 

u_longent_total_size; /* 
u_longent_vers; /* 

u_char*ent_data; /* 

u_longent_pri; /* 

}CAM_ERR_ENTRY; 


9.2.1.1 The ent_type Member 

The ent type member contains the type of data in the entry, which can be a string, 
a structure, or a CCB. Numerous types of strings are defined in the 
/usr/sys/h/cam_logger. h file. CCBs are assigned to one of the XPT 
function codes listed in the /usr/sys/h/cam. h file. 

9.2.1.2 The ent_size Member 

The ent_size member contains the size, in bytes, of the data in the entry. 

9.2.1.3 The ent_total_size Member 

The ent_total_size member preserves long-word alignment for compatibility 
with the uerf error-reporting utility. The cam_logger routine fills in this 
member. See the Guide to the Error Logger for information about the uerf utility. 


{ 

String, TAPE_SPECIFIC, CCB, etc */ 
Size of the data (CCB, TAPE_SPEC)*/ 
To preserve alignment (uerf) */ 
Version number of type */ 

Pointer to whatever string, etc */ 
FULL or Brief uerf output */ 
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9.2.1.4 


9.2.1.5 


9.2.1.6 


9.2.2 


9.2.2.1 


9.2.2.2 


The ent_vers Member 

The ent_vers member is the version number of the contents of the ent_type 
member. See the #def ine PDRV_DEVICE_VERS line in the 
/usr/sys/h/pdrv. h file for an example of associating a version number with a 
structure. 

The ent_data Member 

The ent data member contains a pointer to the contents of the ent_type 
member. 

The ent_prl Member 

The ent_pri member contains the output from the uerf utility, which can be in 
brief or full report format. See the Guide to the Error Logger for information about 
the uerf utility. 


The Error Header Structure 


The Error Header Structure, CAM_ERR_HDR, contains all the data needed by the 
uerf utility to determine that the packet is a CAM error log packet. See the Guide 
to the Error Logger for information about the uerf utility. The structure is defined 
as follows: 


typedef struct cam_err_hdr { 


u_short hdr_type; 

/* 

u_long 

hdr_size; 

/* 

u_char 

hdr_class; 

/* 

u_long 

hdr_subsystem; 

/* 


u_long hdrentries; /* 

CAM_ERR_ENTRY *hdr_list; 
u_long hdr_pri; /* 

}CAM_ERR_HDR; 


Packet type - CAM_ERR_PKT */ 

Filled in by cam_logger */ 

Sub system class Tape, disk, 

* sii_dme , etc.. 

V 

* Mostly for controller type 

* But the current errloger uses 

* disk tape etc if no controller 

* is known.. So what we will do 

* is dup the disk and tape types 

* in the lower number 0 - If and 

* the controllers asc sii 5380 

* etc can use the uppers. 

V 

Number of error entries in list*/ 

/* Pointer to list of error entries*/ 
Error logger priority. */ 


The hdr_type Member 

The hdr type member contains the error-packet type, which must be 
CAM_ERR_PKT. 

The hdr_slze Member 

The hdr_size member is filled in by the cam_logger routine. 
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9.2.2.3 The hdr_class Member 

The hdr_class member identifies the CAM module that detected the error and 
assigns it to one of the Defined Device Types listed in the 
/usr/sys/h/scsi_all. h file. The device classes are defined in the 
/usr/sys/h/cam_logger. h file. 

9.2.2.4 The hdr_subsystem Member 

The hdr subsystem member identifies the CAM subsystem controller that 
detected the error and assigns it to one of the Defined Device Types listed in the 
/usr/sys/h/scsi_all. h file. The device classes are defined in the 
/usr/sys/h/cam_logger. h file. 


9.2.2.5 The hdr_entrles Member 

The hdr_entri.es member contains the number of entries in the header list. 

9.2.2.6 The hdrjist Member 

The hdr_list member contains a pointer to a list of error entries. 

9.2.2.7 The hdr_pri Member 

The hdr_pri member identifies the priority of the error and assigns it to one of the 
priorities listed in the /usr/sys/io/cam/errlog. h file. 


9.3 The cam Jogger Routine 

The cam_logger routine allocates a system error log buffer and fills in a uerf 
error log packet. The routine fills in the bus, target, and LUN information from the 
Error Header Structure passed to it and copies the Error Header Structure and the 
Error Entry Structures and data to the error log buffer. 
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This chapter describes the debugging macros and routines provided by Digital for 
SCSI/CAM peripheral device driver writers. 

10.1 CAM Debugging Variables 

There are two levels of debugging within the CAM modules: debugging independent 
of a bus, target, or LUN, and debugging that tracks a specific bus, target, or LUN. 
USCA debugging is turned on by defining the program constant CAMDEBUG in the 
/usr/sys/io/cam/cam_debug. h file and recompiling the source files. 

This section describes the variables that contain the information for each level of 
debugging the CAM subsystem. The variables are: 

• camdbg_f lag - Which turns on specific cprintf calls within the kernel, 
depending on its setting, to capture information independent of a particular SCSI 
ID. 

• camdbg_id - Which contains the specific bus, target, and LUN information for 
tracking. 

The macros, PRINTD and CALLD, use the variables for tracking target-specific 
messages and for allowing specific subsets of the DEBUG statements to be printed. 
The macros are defined in the /usr/sys/io/cam/cam_debug. h file. 


10.1.1 The camdbg_flag Variable 

The most significant bit, bit 31, of the camdbg_f lag variable is the bit that 
indicates whether the target information is valid. If set, it indicates that the 
camdbg id variable contains valid bus, target, and LUN information for the device 
to be tracked. Bits 30 to 0 define the debug flag setting. The possible settings, in 
ascending hexadecimal order, with a brief description of each, follow: 


Flag Name Description 


CAMD_INOUT 

CAMD_FLOW 

CAMD_PHASE 

CAMD_SM 

CAMD_ERRORS 

CAMD_CMD_EXP 

CAMD_IO_MAPPING 

CAMD_DMA_FLOW 

CAMD DISCONNECT 


Routine entry and exit 
Code flow through the modules 
SCSI phase values 
State machine settings 
Error handling 

Expansion of commands and responses 
DME I/O mapping for user space 
DME Dynamic Memory Allocation flow 
Signal disconnect handling 




Flag Name 

Description 

CAMD_TAGS 

Tag queuing code 

CAMD_POOL 

XPT tracking in the DEC CAM packet pool 

CAMD_AUTOS 

Autosense handling 

CAMD_CC BALLOC 

CCB allocation and free flow 

CAMD_MSGOUT 

Messages going out 

CAMD_MSGIN 

Messages coming in 

CAMD_STATU S 

SCSI status bytes 

CAMD_CONFIG 

CAM configuration paths 

CAMD_SCHED 

SIM scheduler points 

CAMD_SIMQ 

SIM queue manipulation 

CAMDJTAPE 

SCSI/CAM peripheral tape flow 

CAMD_COMMON 

SCSI/CAM peripheral common flow 

CAMD_DISK 

SCSI/CAM peripheral disk flow 

CAMD_DISK_REC 

SCSI/CAM peripheral disk recovery flow 

CAMD_DBBR 

SCSI/CAM peripheral disk Dynamic Bad Block 
Recovery flow 

CAMD_CD ROM 

SCSI/CAM peripheral CDROM functions 

CAMD_INTERRUPT 

SIM trace Interrupts 

TVALID 

The bus, target, and LUN bits are valid in the 
camdbg_id variable 


10.1.2 The camdbgJd Variable 

The camdbg_id variable contains the bus, target, and LUN (B/T/L) information for 
a specific target to track for debugging information. In the current implementation, 
the bits are divided into three parts, with the remainder reserved. The bits are 
allocated as follows: bits 31 to 16, Reserved; bits 15 to 8, Bus number; bits 7 to 4, 
Target number; and bits 3 to 0, LUN number. Multiples of four bits are used to 
assign hexadecimal values into the camdbg_id variable. 


10.2 CAM Debugging Macros 

The PRINTD and CALLD macros track target-specific messages and allow specific 
subsets of the debugging statements to be printed. 

This PRINTD macro, which prints debugging information if CAMDEBUG is 
defined, follows. 

/* 

* Conditionally Print Debug Information. 

*/ 

#if defined(CAMDEBUG) && Idefined(lint) 

# define PRINTD(B, T, L, F, X) 

{ \ GO 

/* NOSTRICT */ \ 

if( camdbg_flag & (int)F ) \ @ 

{ \ 
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if ( ( (camdbg_flag & TVALID) -==0) || \ S 
(((camdbg_flag & TVALID) 1= 0) £,& \ 0 
((((camdbg_id & BMASK) >> BSHIFT) — B) || 

((((camdbg_id & TMASK) >> TSHIFT) == T) || 

( ( ( (camdbg_id & LMASK) >> LSHIFT) ««= L) || 

t \ 

/* VARARGS */ \ 

(void)(*cdbg_printf) X ; \ 

} \ 

} \ 

} 

flendif /* 1 defined(lint) 


(B == NOBTL)) && \ @ 
(T == NOBTL)) && \ 

(L == NOBTL))) ) \ 


BQ The B, T, and L arguments are for target-specific tracking. The F argument is a 
flag for tracking specific subsets of the printf statements. The F flag argument 
is compared with the camdbg_f lag variable to determine if the user wants to 
see the message. The X argument must be a complete printf argument set 
enclosed within parentheses, (), to allow the preprocessor to include it in the final 
printf statement. 

0 This statement checks to see if any of the flags for the PRINT'D macro are turned 
on. It does not look for an exact match so that the same PRINTD macro can be 
used for different settings of the flags in camdbg_f lag. 

i This section of code checks for any target information available for tracing a 
target. The first condition checks to see if the target valid bit is not set. If it is 
not, the OR condition is met and the call to the printf utility is made. 

0 If the TVALID bit is set, the bus, target, and LUN fields in the camdbg_id 
variable must be compared to the B, T, and L arguments. If TVALID is true and 
bus equals B, target equals T, and LUN equals L, then also print. 

HI This construct checks the B, T, and L fields. For example, the following 
statement checks the B field: 

((((camdbg_id & BMASK) >> BSHIFT) == B) || (B == NOBTL)) 

The statement masks out the other fields and shifts the bus value down to allow 
comparision with the B argument. The arguments can also have a “wildcard” 
value, NOBTL. When the wildcard value is used, the B or T or L comparision is 
always true. 


The CALLD macro uses the same if statement constructs to conditionally call a 
debugging function using the following define statement: 

# define CALLD(B, T, L, F, X) 


10.3 CAM Debugging Routines 

The SCSI/CAM peripheral device debugging routines can be allocated into categories 
as follows: 

• Routines that generate reports on CAM functions and status in either a brief form 
listing the name as it is defined in the applicable header file, or in the form of a 
sentence. The following routines are in this category: 

- cdbg_CamFunction 

- cdbg_CamStatus 
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- cdbg_ScsiStatus 

- cdbg_SystemStatus 

• Routines that dump the contents of CCBs, SCSI/CAM Peripheral Device Driver 
Working Set Structures, and other SCSI/CAM commands for examination. The 
following routines are in this category: 

- cdbg_DumpCCBHeader 

- cdbg_DumpCCBHeaderFlags 

- cdbg_DumpSCSIIO 

- cdbg_DumpPDRVws 

- cdbg_DumpABORT 

- cdbg_DumpTERMIO 

- cdbg_DumpBu f f er 

- cdbg_GetDeviceName 

- cdbg_DumpInquiryData 

Descriptions of the routines with syntax information, in ULTRIX reference page 
format, are included in alphabetical order in Appendix C. 

10.3.1 CAM Debugging Status Routines 

This section describes the SCSI/CAM peripheral device debugging routines that 
report status. Table 10-1 lists the name of each routine and gives a summary 
description of its function. The sections that follow contain a more detailed 
description of each routine. 


Table 10-1: CAM Debugging Status Routines 


Routine 

Summary Description 

cdbg_CamFunction 

reports CAM XPT function codes 

cdbg_CamStatus 

decodes CAM CCB status codes 

cdbg_ScsiStatus 

reports SCSI status codes 

cdbg_SystemStatus 

reports system error codes 


10.3.1.1 The cdbg_CamFunction Routine 

The cdbg_CamFunction routine reports CAM XPT function codes. Program 
constants are defined to allow either the function code name only or a brief 
explanation to be printed. The XPT function codes are defined in the 
/usr/sys/h/cam.h file. 

10.3.1.2 The cdbg.CamStatus Routine 

The cdbg_CamStatus routine decodes CAM CCB status codes. Program 
constants are defined to allow either the status code name only or a brief explanation 
to be printed. The CAM status codes are defined in the /usr/sys/h/cam. h file. 
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10.3.1.3 The cdbg_ScsiStatus Routine 

The cdbg_ScsiStatus routine reports SCSI status codes. Program constants are 
defined to allow either the status code name only or a brief explanation to be printed. 
The SCSI status codes are defined in the /usr/sys/h/scsi_status . h file. 

10.3.1.4 The cdbg_SystemStatus Routine 

The cdbg_SystemStatus routine reports system error codes. The system error codes 
are defined in the /usr/sys/h/errno. h file. 

10.3.2 CAM Dump Routines 

This section describes the SCSI/CAM peripheral device debugging routines that 
dump contents for examination. Table 10-2 lists the name of each routine and gives 
a summary description of its function. The sections that follow contain a more 
detailed description of each routine. 

Table 10-2: CAM Dump Routines 


Routine 


Summary Description 


cdbg_DumpCCBHeader 

cdbg_DumpCCBHeaderFlags 

cdbg_DumpSCSIIO 
cdbg_DumpPDRVws 

cdbg_DumpABORT 
cdbg_DumpTERMIO 
cdbg_DumpBuf fer 

cdbg_GetDeviceName 

cdbg_DumpInquiryData 


dumps the contents of a CAM Control Block (CCB) 
header structure 

dumps the contents of the cam_f lags member of 
a CAM Control Block (CCB) header structure 
dumps the contents of a SCSI I/O CCB 
dumps the contents of a SCSI/CAM Peripheral 
Device Driver Working Set Structure 
dumps the contents of an ABORT CCB 
dumps the contents of a TERMINATE I/O CCB 
dumps the contents of a data buffer in hexadecimal 
bytes 

returns a pointer to a character string describing the 
dtype member of an ALL_INQ_DATA structure 
dumps the contents of an ALL_INQ_DATA 
structure 


10.3.2.1 The cdbg_DumpCCBHeader Routine 

The cdbg_DumpCCBHeader routine dumps the contents of a CAM Control Block 
(CCB) header structure. The CAM Control Block (CCB) header structure is defined 
in the /usr/sys/h/cam. h file. 

10.3.2.2 The cdbg_DumpCCBHeaderFlags Routine 

The cdbg_DumpCCBHeaderFlags routine dumps the contents of the 

cam f lags member of a CAM Control Block (CCB) header structure. The CAM 

Control Block (CCB) header structure is defined in the /usr/sys/h/cam. h file. 


USCA Debugging Facilities 10-5 



10.3.2.3 The cdbg_DumpSCSIIO Routine 

The cdbg_DumpSCSHO routine dumps the contents of a SCSI I/O CCB. The 
SCSI I/O CCB is defined in the /usr/sys/h/cam. h file. 

10.3.2.4 The cdbg_DumpPDRVws Routine 

The cdbg_DumpPDRVws routine dumps the contents of a SCSI/CAM Peripheral 
Device Driver Working Set Structure. The SCSI/CAM Peripheral Device Driver 
Working Set Structure is defined in the /usr/sys/h/pdrv. h file. 

10.3.2.5 The cdbg.DumpABORT Routine 

The cdbg_DumpABORT routine dumps the contents of an ABORT CCB. The 
ABORT CCB is defined in the /usr/sys/h/cam. h file. 

10.3.2.6 The cdbg_DumpTERMIO Routine 

The cdbg_DumpTERMIO routine dumps the contents of a TERMINATE I/O CCB. 
The TERMINATE I/O CCB is defined in the /usr/sys/h/cam. h file. 

10.3.2.7 The cdbg.DumpBuffer Routine 

The cdbg_DumpBuf f er routine dumps the contents of a data buffer in 
hexadecimal bytes. The calling routine must display a header line. The format of the 
dump is 16 bytes per line. 

10.3.2.8 The cdbg_GetDeviceName Routine 

The cdbg_GetDeviceName routine returns a pointer to a character string 
describing the dtype member of an ALL_INQ_DATA structure. The 
ALL_INQ_DATA structure is defined in the /usr/sys/h/scsi_all . h file. 

10.3.2.9 The cdbg_DumplnquiryData Routine 

The cdbg_DumplnquiryData routine dumps the contents of an 
ALL_INQ_DATA structure. The ALL_INQ_DATA structure is defined in the 
/usr/sys/h/scsi_all. h file. 
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Programmer-Defined SCSI/CAM Device 

Drivers 



This chapter describes how programmers can write their own device drivers for 
SCSI/CAM peripheral devices using a combination of common data structures and 
routines provided by Digital and programmer-defined routines and data structures. 
This chapter describes only the programmer-defined data structures and routines. See 
Chapter 3 for a description of the common data structures and routines. 

The chapter also describes how to add a programmer-defined device driver to the 
USCA system. 


11.1 Programmer-Defined SCSI/CAM Data Structures 

This section describes the SCSI/CAM peripheral data structures programmers must 
use if they write their own device drivers. The following data structures are 
described: 

• PDRV_UNIT_ELEM - The Peripheral Device Unit Table 

• PDRVJDEVICE - The Peripheral Device Structure 

• DEVJDESC - The Device Descriptor Structure 

• DENSITY_TBL - The Density Table Structure 

• MODESEL_TBL - The Mode Select Table Structure 

11.1.1 Programmer-Defined Peripheral Device Unit Table 

The Peripheral Device Unit Table is an array of SCSI/CAM peripheral device unit 
elements. The size of the array is the maximum number of possible devices, which 
is determined by the maximum number of SCSI controllers allowed for the system. 
The structure is allocated statically and is defined as follows: 

typedef struct pdrvunitelem { 

PDRV_DEVICE *pu_device; 
u_short pu_opens; 
u_short pu_config; 

u_char pu_type; 

} PDRV_UNIT_ELEM; 


11.1.1.1 The pu_device Member 

The pu device field is filled in with a pointer to a CAM-allocated peripheral SCSI 
device (PDRV_DEVICE) structure when the first call to the ccmn_open_unit 
routine is issued for a SCSI device that exists. 


/* Pointer to peripheral device structure */ 
/* Total number of opens against unit */ 

/* Indicates whether the device type */ 

/* configured at this address */ 

/* Device type - byte 0 from inquiry data */ 




11.1.1.2 The pu_opens Member 

The total number of opens against the unit. 

11.1.1.3 The pu_config Member 

Indicates whether a device of the specified type is configured at this bus/target/LUN. 

11.1.1.4 The pu_type Member 

The device type from byte 0 (zero) of the Inquiry data. 

11.1.2 Programmer-Defined Peripheral Device Structure 

A SCSI/CAM peripheral device structure, PDRV_DEVICE, is allocated for each 
SCSI device that exists in the system. The PDRV_DEVICE structure is defined as 
follows: 

typedef struct pdrv_device { 

PD_LIST pd_active_list; /* Forward active pointer of CCBs */ 

/* which have been sent to the XPT */ 
u_long pd_active_ccb; /* Number of active CCBs on queue */ 

u_long pd_que_depth; /* Tagged queue depth - indicates the */ 

/* maximum number of commands the unit */ 

/* can store internally */ 

PD__LIST pd_pend_list; /* Forward active pointer of pending CCBs */ 

/* which have not been sent to the XPT due */ 
/* to a full queue for tagged requests */ 
u_long pd_pend_ccb; /* Number of pending CCBs */ 

dev_t pd_dev; /* CAM major/minor number */ 

u_char pd_bus; /* SCSI controller number */ 

u_char pd_target; /* SCSI target id */ 

u_char pd_lun; /* SCSI target lun */ 

uchar pd_unit; /* Unit number */ 

u_long pd_soft_err; /* Number of soft errors */ 

ulong pdharderr; /* Number of hard errors */ 

u_short pd_soft_err_limit;/* Max no. of soft errors to report */ 

u_short pd_hard_err_limit;/* Max no. of hard errors to report */ 

u_long pd_flags; /* Specific to peripheral drivers */ 

u_char pd_state; /* Specific to peripheral drivers - can */ 

/* be used for recovery */ 

u_char pd_abort_cnt; /* Specific to peripheral drivers - can */ 

/* be used for recovery */ 

u_long pd_cam_flags; /* Used to hold the default settings */ 

/* for the cam_flags field in CCBs */ 
uchar pdtagaction; /* Used to hold the default settings for */ 

/* the camtagaction field of the SCSI */ 

/* I/O CCB */ 

u_char pd_dev_inq[INQLEN]; 

/* Inquiry data obtained from GET */ 

/* DEVICE TYPE CCB */ 

u_long pd_ms_index; /* Contains the current index into the */ 

/* Mode Select Table when sending Mode */ 

/* Select data on first open */ 

DEV_DESC *pd_dev_desc; /* Pointer to our device descriptor */ 
caddr_t pdspecific; /* Pointer to device specific info */ 

ushort pd_spec_size; /* Size of device specific info */ 

caddr_t pd_sense_ptr; /* Pointer to the last sense data */ 

/* bytes retrieved from device */ 
u_short pd_sense_len; /* Length of last sense data */ 
void (*pd_recov_hand)(); 

/* Specific to peripheral drivers - can */ 
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} 


/* be used to point to the recovery */ 
/* handler for the device */ 
u_long pd_read_count; /* Number of reads to device */ 

u_long pd_write_count; /* Number of writes to device */ 

u_long pd_read_bytes; /* Number of bytes read from device */ 

u_long pd_write_bytes; /* Number of bytes written to device */ 

struct lock_t pd_lk_device; 

/* SMP lock for the device */ 


PDRV DEVICE 


11.1.2.1 The pd_actlve Jlst Member 

A pointer to the first CCB on the active queue. 

11.1.2.2 The pd_actl ve _ccb Member 

The number of CCBs on the active queue. 

11.1.2.3 The pd_que_depth Member 

The depth of the tagged queue, which is the maximum number of commands that the 
peripheral driver will send to the SCSI device. 

11.1.2.4 The pd_pendJlst Member 

A pointer to the first CCB on the pending queue. 

11.1.2.5 The pd_pend_ccb Member 

The number of CCBs on the pending queue. 

11.1.2.6 The pd.dev Member 

The major/minor device number pair that identifies the bus number, target ID, and 
LUN associated with this SCSI device. 

11.1.2.7 The pd J>us Member 

SCSI target’s bus controller number. 

11.1.2.8 The pd Jarget Member 

SCSI target’s ID number. 

11.1.2.9 The pd Jun Member 

SCSI target’s logical unit number. 

11.1.2.10 The pd.unlt Member 

SCSI device’s unit number. 
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11.1.2.11 The pdjlags and pd_state Members 

These are specific to SCSI/CAM peripheral device drivers. They can be used for 
recovery. 

11.1.2.12 The pd_abort_cnt Member 

This is specific to SCSI/CAM peripheral device drivers. It can be used for recovery. 

11.1.2.13 The pd_cam Jlags Member 

This contains the default settings for the cam_f lags field in the CAM Control 
Block (CCB) header structure. The flags are defined in the /usr/sys/h/cam. h 
file. 

11.1.2.14 The pd Jag_action Member 

This contains the default settings for the HBA/SIM queue actions field, 
cam_tag_action, in the SCSI I/O CCB structure. The queue actions are defined 
in the /usr/sys/h/cam. h file. 

11.1.2.15 The pd jfevJnq Member 

This is inquiry data. 

11.1.2.16 The pd jnsJndex Member 

The current index into the Mode Select Table that is pointed to in the Device 
Descriptor Structure. 

11.1.2.17 The pd_dev_desc Member 

A pointer to the DEV_DESC structure for the SCSI device. 

11.1.2.18 The pd.specific Member 

A pointer to a device-specific structure filled in by the ccmn_open_unit routine. 

11.1.2.19 The pd_spec_slze Member 

The size of the device-specific information. 

11.1.2.20 The pd_sense_ptr Member 

A pointer to the last sense data bytes retrieved from the device. 

11.1.2.21 The pd_senseJen Member 

The length, in bytes, of the last sense data retrieved from the device. 

11.1.2.22 The pd_recov_hand Member 

This is specific to SCSI/CAM peripheral device drivers. It can be used to point to 
the recovery handler for the device. 
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11.1.2.23 The pd_read_count Member 

Number of read operations from device. Used for performance statistics. 

11.1.2.24 The pd_write_count Member 

Number of write operations to device. Used for performance statistics. 

11.1.2.25 The pd_read_bytes Member 

Total number of bytes read from device. Used for performance statistics. 

11.1.2.26 The pd_write_bytes Member 

Total number of bytes written to device. Used for performance statistics. 

11.1.2.27 The pd_lk_devlce Member 

The lock structure. 


11.1.3 Programmer-Defined Device Descriptor Structure 

A Device Descriptor Structure entry, DEV_DESC, must be added to the 
cam_devdesc_tab for each programmer-defined SCSI device that exists in the 
system. The file /usr/sys/data/cam_data. c contains examples of entries 
supplied by Digital. The DEV_DESC structure is defined as follows: 


typedef struct 
u char 


u_char 
u char 


u_long 

struct 

u_long 

u_long 

DENSITY 

MODESEL 


dev_desc { 

dd_pv_name[IDSTRING_SIZE]; 

/* Product ID and vendor string from */ 
/* Inquiry data */ 

dd_length; /* Length of dd_pv_name string */ 

dd_dev_name[DEV_NAME_SIZE] ; 

/* Device name string - see defines */ 
/* in devio.h */ 

dd_device_type; /* Bits 0-23 contain the device */ 

/* class, bits 24-31 contain the */ 

/* SCSI device type */ 
pt_info *dd_def_partition; 

/* Default partition sizes - disks */ 
dd_block_size; /* Block/sector size */ 
dd_max_record; /* Maximun transfer size in bytes */ 

/* allowed for the device */ 

_TBL *dd_density_tbl; 

/* Pointer to density table - tapes */ 
TBL *dd_modesel_tbl; 

Je select table pointer - used */ 


u_long 

u_long 

u_long 

u_short 

u_char 

u_char 
u char 



/* 


/* 

dd_flags; 

/* 

dd_scsi_optcmds;/* 

dd_ready_time 

; /* 

dd_que_depth ; 

/* 


/* 

dd_valid; 

/* 


/* 

dd_inq_len; 

/* 

dd_req_sense_ 

len; 


/* 


/* 


on open and recovery */ 


Time in seconds for powerup dev ready 
Device queue depth for devices */ 


fields are valid */ 

/* Inquiry data length for device */ 

Request sense data length for */ 
/* this device */ 


}DEV DESC; 
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11.1.3.1 


11.1.3.2 


11.1.3.3 


11.1.3.4 


11.1.3.5 


11.1.3.6 


11.1.3.7 


11.1.3.8 


The dd_pv_name Member 

The product ID and vendor returned string identifying the drive obtained from the 
Inquiry data. The product ID makes up the first eight characters of the string. The 
IDSTRINGJSIZE constant is defined in the /usr/sys/h/pdrv. h file. 


The ddjength Member 

This specifies the length of the dd_pv_name string. The match is made on the total 
string returned by the unit. 

The dd_dev_name Member 

The ULTRIX device name string, which is defined in the /usr/sys/h/devio. h 
file. A generic name of DEV_RZxx should be used for non-Digital disk devices. 

The following generic names are provided for tapes: DEV_TZQIC, for 1/4-inch 
cartridge tape units; DEV_TZ9TK for 9-track tape units; DEV_TZ8MM, for 8- 
millimeter tape units; DEV_TZRDAT, for RDAT tape units; DEV_TZ3480, for IBM 
3480-compatible tape units; and DEV_TZxx, for tape units that do not fit into any of 
the predefined generic categories. 

The dd_deviceJype Member 

Bits 24-31 contain the SCSI device class, for example, ALL_DTYPE_DIRECT, 
which is defined in the /usr/sys/h/scsi_all. h file. The bits 0-23 contain the 
device subclass, for example, SZ_HARD_DISK, which is defined in the 
/usr/sys/h/pdrv. h file. 

The dd_def_partition Member 

A pointer to the default partition sizes for disks, which are defined in the 
/usr/sys/data/cam_data . c file. Tape devices should define this as 
sz_null_sizes . Disk devices may use sz_rzxx_sizes, which assumes that 
the disk has at least 48 Mbytes. The sz_rzxx_sizes should not be modified. If 
you want to create your own partition table, make an entry for your device in the 
device descriptor table in the /usr/sys/data/cam_data . c file. 

The dd_block_size Member 

The block or sector size of the unit, in bytes, for disks and CDROMs. You can 
obtain the correct number of bytes from the documentation for your device. 

The dd_max_record Member 

The maximum number of bytes that can be transferred in one request for raw I/O. 
Errors result if your system does not have enough physical memory or if the unit 
cannot handle the size of transfer specified. 

The dd_denslty_tbl Member 

A pointer to the Density Table Structure entry for a tape device. 
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11.1.3.9 The ddjriodeseljbl Member 

A pointer to the Mode Select Table Structure entry for the devices. The Mode Select 
Table Structure is read and sent to the SCSI device when the first open call is issued 
and during recovery. This field is optional and should be used only for advanced 
SCSI device customization. 

11.1.3.10 The dd.flags Member 

The option flags, which can be SZ_NOSYNC, indicating that the device cannot 
handle synchronous transfers; SZ_BBR, indicating that the device allows bad block 
recovery; SZ_NO_DISC, indicating that the device cannot handle disconnects; and 
SZ_NO_TAG, indicating tagged queueing is not allowed. SZ_NO_TAG overrides 
inquiry data. The flags are defined in the /usr/sys/h/pdrv. h file. 


11.1.3.11 The dd_$csi_optcmds Member 

The optional SCSI commands that are supported, as defined in the 
/usr/sys/h/pdrv. h file. The possible commands are NO_OPT_CMDS; 
SZ_RW10, which enables reading and writing 10-byte CDBs; SZ_PREV_ALLOW, 
which prevents or allows media removal; and SZ_EXT_RESRV, which enables 
reserving or releasing file extents. 

11.1.3.12 The dd_ready_tlme Member 

The maximum time, in seconds, allowed for the device to power up. For disks, this 
represents power up and spin up time. For tapes, it represents power up, load, and 
rewind to Beginning of Tape. 

11.1.3.13 The dd_que_depth Member 

The maximum number of queued requests for devices that support queueing. Refer 
to the documentation for your device to determine if your device supports tag 
queuing and, if so, the depth of the queue. 

11.1.3.14 The dd_valid Member 

This indicates which data length fields are valid. The data length bits, 
DD_REQSNS_VAL and DD_INQ_VAL, are defined in the /usr/sys/h/pdrv. h 
file. 

11.1.3.15 The ddjnqjen Member 

The inquiry data length for the device. This field must be used in conjunction with 
the DD_INQ_VAL flag. 

11.1.3.16 The dd_req__sensejen Member 

The request Sense data length for the device. This field must be used in conjunction 
with the DD_REQSNS_VAL flag. 
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11.1.4 


11.1.4.1 

11.1.4.2 

11.1.4.3 

11.1.4.4 

11.1.4.5 

11.1.4.6 


Programmer-Defined Density Table Structure 

The Density Table Structure allows for the definition of eight densities for each type 
of SCSI tape device unit. A density is defined using the lower three bits of the unit’s 
minor number. Refer to the SCSI tape device unit documentation for the density 
code, compression code, and blocking factor for each density. 

The /usr/sys/data/cam_data . c file contains Density Table Structure entries 
for all devices known to Digital. Programmers can add entries for other SCSI tape 
devices at the end of the Digital entries. The definition for the Density Table 
Structure, DENSITY_TBL, follows: 

typedef struct density_tbl { 
struct density! 


u_char 

u_char 

den_flags; 

den_density_code; 

/* 

VALID, ONE_FM etc */ 

u_char 

den_compress_code; 

/* 

Compression code if supported */ 

u_char 

den_speed_setting; 

/* 

for this density */ 

u_char 

den_buffered_setting; 

/* 

Buffer control setting */ 

u_long 

den_blocking; 

/* 

0 variable etc. */ 

} density [MAX_ 

_TAPE_DENSITY] ; 




}DENSITY_TBL; 


The den_flags Member 

The den_f lags specified indicate which fields in the DENSITY_TBL structure are 
valid for this density. The flags are: DENS_VALID, to indicate whether the structure 
is valid; ONE_FM, to write one file mark on closing for QIC tape units; 
DENS_SPEED_VALID, to indicate the speed setting is valid for multispeed tapes; 
DENS_BUF_VALID, to run in buffered mode; and DENS_COMPRESS_VALID, to 
indicate compression code, if supported. 

The den_density_code Member 

The den_density_code member contains the SCSI density code for this density. 


The den_compress_code Member 

The den_compress_code member contains the SCSI compression code for this 
density, if the unit supports compression. 

The den_speed_sett!ng Member 

The den_speed_setting member contains the speed setting for this density. 
Some units support variable speed for certain densities. 

The den_buffered_setting Member 

The den buf f ered setting member contains the buffer control setting for this 
density. 

The den_blocking Member 

The den blocking member contains the blocking factor for this SCSI tape device. 
A NULL (0) setting specifies that the blocking factor is variable. A positive value 
represents the number of bytes in a block, for example, 512 or 1024. 
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11.1.4.7 Sample Density Table Structure Entry 

This section contains a sample portion of a Density Table Structure entry for the 
TZK10 SCSI tape device, which supports both fixed and variable length records: 

DENSITY_TBL 
tzklO_dens = { 

{ Minor 00 

Flags 

DENS_VALID | DENS_BUF_VALID |ONE_FM , 

Density code Compression code Speed setting 

SEQ_8000R_BPI, NULL, NULL, 

Buffered setting Blocking 

1, 512 


{ Minor 06 
Flags 

DENS_VALID | DENS_BUF_VALID |ONE_FM , 


Density code Compression code 

Speed 

setting 

SEQ_QIC320, 

NULL, 


NULL, 

Buffered setting 

Blocking 



1, 

), 

{ Minor 07 

1024 



Flags 




DENS_VALID | DENS_ 

_BUF_VALID |ONE_FM , 



Density code Compression code 

Speed 

setting 

SEQ_QIC320, 

NULL, 


NULL, 

Buffered setting 

Blocking 



1, 

} 

NULL 




]; end of tzklO_dens 


11.1.5 Programmer-Defined Mode Select Table Structure 

The Mode Select Table Structure is read and sent to the SCSI device when the first 
call to the SCSI/CAM peripheral open routine is issued on a SCSI device. There can 
be a maximum of eight entries in the Mode Select Table Structure. The definition for 
the Mode Select Table Structure, MODESEL_TBL, follows: 

typedef struct modeseltbl { 
struct msentryf 

u_char ms_page; /* Page number */ 

u_char *ms_data; /* Pointer to Mode Select data */ 

u_char ms_data_len; /* Mode Select data length */ 
u_char ms_ent_sp_pf;/* Save Page and Page format bits */ 

/* BIT 0 l=Save Page, */ 

/* 0=Don't Save Page */ 

/* BIT 1 l=SCSI-2, 0=SCSI-1 */ 

}ms_entry[MAX_OPEN_SELS]; 

]MODESEL_TBL; 
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11.1.5.1 The ms_page Member 

The ms_page member contains the SCSI page number for the device type. For 
example, the page number would be 0x10 for the device configuration page for a 
SCSI tape device. 


11.1.5.2 The ms.data Member 

The ms_data member contains a pointer to the mode select data for the device. Set 
up the page data and place the address of the page structure in this field. A sample 
page definition for page 0x10 for the TZK10 follows: 

SEQ_MODE_DATA6 
tzklO_pagelO = { 

{ Parameter header 


mode_len medium 

NULL, NULL, 

Buf_mode wp 

0x01, NULL, 

1 / 

{ Mode descriptor 


type 


speed 

NULL, 

blk_desc_len 

Sizeof(SEQ_MODE_DESC) 


Density num_blks2 


num blksl 


NULL, 

NULL, 

NULL, 

num_blks0 

reserved 

blk_len2 

NULL, 


NULL, 

blk_lenl 

blk_len0 


NULL, 

NULL 



1 / 

{ 

Page data for page 0x2 


PAGE header 
byteO bytel 
0x10, OxOe, 


byte2 

byte3 

byte4 

byte5 

byte6 

0x00, 

0x00, 

40, 

40, 

NULL, 

byte7 

byte8 

byte9 

bytelO 

bytell 

NULL, 

OxeO, 

NULL, 

0x38, 

NULL, 

bytel2 

bytel3 

bytel4 

bytel5 


NULL, 

NULL, 

NULL, 

NULL 



1 

1 ; 


11.1.5.3 The ms_data Jen Member 

The ms_data_len member contains length of a page, which is the number of bytes 
to be sent to the device. 
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11.1.5.4 The ms_ent_sp_pf Member 

The ms_ent_sp_pf member contains flags for the MODE SELECT CDB that the 
device driver formats. 


11.1.5.5 Sample Mode Select Table Structure Entry 

This section contains a sample portion of a Mode Select Table Structure entry for the 
TZK10 SCSI tape device: 


MODESEL_TBL 
tzklOmod = { 

{ MODE PAGE ENTRY 1 


Page number 
0x02, 


The data pointer 
(u_char *)&tzkl0_page2, 


Data len 
28, 


SCSI2?? 

0x2 


{ MODE PAGE ENTRY 8 

Page number 
NULL, 

Data len 
NULL, 

}, 

}; 


The data pointer 
(u_char *)NULL, 

SCSI2?? 

NULL 


11.2 Sample SCSI/CAM Device-Specific Data Structures 

This section provides samples of the SCSI/CAM peripheral data structures 
programmers must define if they write their own device drivers. The following data 
structures are described: 

• TAPE_SPECIFIC - The Tape-Specific Structure 

• DISK_SPECIFIC - The Disk- and CDROM-Specific Structure 


11.2.1 Programmer-Defined Tape-Specific Structure 

SCSI/CAM peripheral device driver writers can create their own tape-specific data 
structures. A sample TAPE_SPECIFIC structure for a SCSI tape device, as defined 
in the /usr/sys/io/cam/cam_tape. h file, follows: 

typedef struct { 

u_long ts_flags; /* Tape flags - BOM,EOT */ 

u_long ts_state_flags; /* STATE - UNIT_ATTEN, RESET etc. */ 
u_long ts_resid; /* Last operation residual count */ 

u_long ts_block_size; /* See below for a complete desc. */ 
u_long ts_density; /* What density are we running at */ 

u_long ts_records; /* How many records in since last tpmark */ 

u_long ts_num_filemarks; /* number of file marks into tape */ 
u_long ts_softcnt; /* Number of soft errors */ 

u_long ts_hardcnt; /* Number of hard errors */ 

}TAPE_SPECIFIC; 
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11.2.1.1 The ts_flags Member 

Flags used to indicate tape condition. The possible flags are: 


Flag Name 

Description 

CTAPE_BOM 

The tape is positioned at the beginning. 

CTAPE_EOM 

The unit is positioned at the end of media. 

CTAPE_OFFLINE 

The device is returning DEVICE NOT READY in 
response to a command. The media is either not 
loaded or is being loaded. 

CTAPE_WRT_PROT 

The unit is either write protected or is opened read 
only. 

CTAPE_BLANK 

The tape is blank. 

CTAPE_WRITTEN 

The tape has been written during this procedure. 

CTAPE_CSE 

Clear serious exception. 

CTAPE_SOFTERR 

A soft error has been reported by the SCSI unit. 

CTAPE_HARDERR 

A hard error has been reported by the SCSI unit. It 
can be reported either through an ioctl or by 
marking the buf structure as EIO. 

CTAPE_DONE 

The tape procedure is finished. 

CTAPE_RETRY 

Indicates a retry can be attempted. 

CTAPE_ERASED 

The tape has been erased. 

CTAPE_TPMARK 

A tape mark has been detected during a read 
opeation. This cannot occur during a write 
operation. 

CTAPE_SHRTREC 

The size of the record retrieved is less than the size 
requested. Reported using an ioctl. 

CTAPE_RDOPP 

Reading in the reverse direction. This is not 
implemented. 

CTAPE_REWINDING 

The tape is rewinding. 

CTAPE_TPMARK_PENDING 

The tape mark is to be reported on the next I/O 
operation. 


11.2.1.2 The ts_state_flags Member 

Flags used to indicate tape state. The possible flags are: 


Flag Name 

Description 

CTAPE_NOT_READY_STATE 

The unit was opened with the FNDELAY flag. The 
unit was detected, but the open failed. 

CTAPE_UNIT_ATTEN_STATE 

A check condition occurred and the sense key was 
UNIT ATTENTION. This usually indicates that the 
media was changed. Current tape position is lost. 
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Flag Name 

Description 

C TAP E_R E S E T_S TAT E 

Indicates a reset condition on the device or on the 
bus. 

CTAPE_RESET_PENDING_STATE 

A reset is pending. 

CTAPE_OPENED_STATE 

The unit is opened. 

CTAPE_DISEOT_STATE 

No notification of end of media is required. 

CTAPE_ABORT_TPPEND_STATE 

CTAPE_AUTO_DENSITY_VALID_STATE 

Indicates that a tape mark was detected for a fixed 
block operation with nonbuffered I/O. The queue is 
aborted. 

Directs the open routine to call the ctz_auto_density 
routine when a unit attention is noticed, because tape 
density has been determined and all reads are to 
occur at that density. 

CTAPE_ORPHAN_CMD_STATE 

This flag is set when a command is orphaned. The 
process does not wait for completion, such as a 
rewind operation. 

CTAPE_POSITION_LOST_STATE 

Tape position is lost due to command failure. 


11.2.1.3 The ts_resid Member 

Residual count from the last tape command. 

11.2.1.4 The ts_block_size Member 

Used to distinguish between blocks and bytes for fixed-block tapes. Commands for 
devices like 9-track tape, which have variable length records, assume bytes. 

11.2.1.5 The ts.density Member 

The current density at which the SCSI tape device is operating. 

11.2.1.6 The ts_records Member 

The number of records read since the last tape mark. 

11.2.1.7 The ts_num_filemarks Member 

The number of file marks encountered since starting to read the tape. 

11.2.1.8 The ts_softcnt Member 

Number of soft errors reported by each SCSI unit. 

11.2.1.9 The ts_hardcnt Member 

Number of hard errors reported by each SCSI unit. 
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11.2.2 Programmer-Defined Disk- and CDROM-Specific Structure 

SCSI/CAM peripheral device driver writers can create their own disk- and CDROM- 
specific data structures. A sample DISK_SPECIFIC structure for a SCSI disk device, 
as defined in the /usr/sys/io/cam/cam_disk. h file, follows: 


typedef struct disk_specific { 
struct buf *ds_bufhd; 


int dsdkn; 

u_long ds_bbr_state; 

ulong ds_bbr_retry; 
CCB_SCSIIO *ds_bbr_rwccb; 
CCB_SCSIIO *ds_bbr_reasccb; 
CCB_SCSIIO *ds_tur_ccb; 

CCB_SCSIIO *ds_start_ccb; 
CCB_SCSIIO *ds_mdsel_ccb; 

CCB_SCSIIO *ds_rdcp_ccb; 

CCB_SCSIIO *ds_read_ccb; 

CCB_SCSIIO *ds_prev_ccb; 

u_long ds_block_size; 

u_long ds_tot_size; 

ulong ds_media_changes; 

struct pt ds_pt; 
u_long ds_openpart; 

}DISK_SPECIFIC; 


/* Anchor for requests which come */ 

/* into strategy that cannot be */ 

/* started due to error recovery */ 

/* in progresss. */ 

/* Used for system statistics */ 

/* Used indicate the current */ 

/* BBR state if active */ 

/* BBR retries for reassignment */ 

/* R/W ccb used for BBR */ 

/* Reassign ccb used for BBR */ 

/* SCSI I/O CCB for tur cmd */ 

/* during recovery */ 

/* SCSI I/O CCB for start unit */ 

/* SCSI I/O CCB for mode select */ 

/* cmd during recovery */ 

/* SCSI I/O CCB for read capacity */ 

/* cmd during recovery */ 

/* SCSI I/O CCB for Read cmd */ 

/* during recovery */ 

/* SCSI I/O CCB for Prevent */ 

/* Media Removal cmd during recovery */ 
/* This units block size */ 

/* Total disk size in blocks */ 

/* Number of times media was */ 

/* changed - removables */ 

/* Partition structure */ 

/* Bit mask of open parts */ 


11.2.2.1 The ds_bufhd Member 

Pointer to a buffer header structure to contain requests that come to the driver but 
cannot be started due to error recovery in progress. The requests are issued when 
error recovery is complete. 

11.2.2.2 The ds.dkn Member 

Used for system statistics. 

11.2.2.3 The ds_bbr_state Member 

Used to indicate the current state if bad block recovery (BBR) is active. 

11.2.2.4 The ds_bbr_retry Member 

Number of retries to attempt for reassignment of bad blocks. 

11.2.2.5 The ds_bbr_rwccb Member 

Pointer for the SCSI I/O CCB for the Read/Write command used for recovery. 
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11.2.2.6 The ds_bbr_reasccb Member 

Pointer for the SCSI I/O CCB for the Reassign command used for recovery. 

11.2.2.7 Theds_tur_ccb Member 

Pointer for the SCSI I/O CCB for the TEST UNIT READY command used for 
recovery. 

11.2.2.8 The ds_start_ccb Member 

Pointer for the SCSI I/O CCB for the START UNIT command used for recovery. 

11.2.2.9 The ds_mdsel_ccb Member 

Pointer for the SCSI I/O CCB for the MODE SELECT command used for recovery. 

11.2.2.10 The ds_rdcp_ccb Member 

Pointer for the SCSI I/O CCB for the Read Capacity command used for recovery. 

11.2.2.11 The ds_read_ccb Member 

Pointer for the SCSI I/O CCB for the Read command used for recovery. 

11.2.2.12 The ds_prev_ccb Member 

Pointer for the SCSI I/O CCB for the Prevent Removal command during recovery. 

11.2.2.13 The ds_block_size Member 

This SCSI disk device’s block size in bytes. 

11.2.2.14 The dsJot_slze Member 

Total SCSI disk device size in blocks. 

11.2.2.15 The ds_media_changes Member 

For removable media, the number of times the media was changed. 

11.2.2.16 The ds_pt Sructure 

Structure defining the current disk partition layout. 

11.2.2.17 The ds_openpart Member 

Bit mask of open partitions. 

11.2.3 SCSI/CAM CDROM/AUDIO I/O Control Commands 

This section describes the standard and vendor-unique I/O control commands to use 
for SCSI CDROM/AUDIO devices. The commands are defined in the 
/usr/sys/io/cam/cam_disk. h file. See Chapter 13 of American National 
Standard for Information Systems, Small Computer Systems Interface - 2 (SCSI - 2), 
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X3T9/89-042 for general information about the CDROM device model. Table 11-1 
lists the name of each command and describes its function. 

Table 11-1: SCSI/CAM CDROM/AUDIO I/O Control Commands 


Command 

Description 

Standard Commands 

CDROM PAUSE PLAY 

Pauses audio operation 

CDROM RESUME PLAY 

Resumes audio operation 

CDROM_PLAY_AUDIO 

Plays audio in Logical Block Address 
(LBA) format 

CDROM_PLAY_AUDIO_MSF 

Plays audio in Minute-/Second-/Frame-units 
(MSF) format 

CDROM PLAY AUDIO TI 

Plays audio track or index 

CDROM PLAY AUDIO TR 

Plays audio track relative 

CDROM TOC HEADER 

Reads Table of Contents (TOC) header 

CDROM TOC ENTRYS 

Reads Table of Contents (TOC) entries 

CDROM_EJECT_CADDY 

Ejects the CDROM caddy 

CDROM READ SUBCHANNEL 

Reads subchannel data 

CDROM_READ_HEADER 

Reads track header 

Vendor-Unique Commands 

CDROM PLAY VAUDIO 

Plays audio LBA format 

CDROM PLAY MSF 

Plays audio MSF format 

CDROM PLAY TRACK 

Plays audio track 

CDROM PLAYBACK CONTROL 

Controls playback 

CDROM PLAYBACK_STATUS 

Checks playback status 

CDROM_SET_ADDRESS_FORMAT 

Sets address format 


11.2.3.1 Structures Used by SCSI/CAM CDROM/AUDIO I/O Control Commands 

Some of the SCSI CDROM/AUDIO device I/O control commands use data 
structures. This section describes those data structures. The structures are defined in 
the /usr/sys/io/cam/cam_disk. h file. Table 11-2 lists the name of each 
structure and the commands that use it. 

Table 11-2: Structures Used by SCSI/CAM CDROM/AUDIO I/O Control 
Commands 


Structure 


Command 


cd_address 

cd_play_audio 

cd_play_audio__ms f 

cd_play_audio_ti 

cd_play_track 

cd toe header 


All 

CDROM_PLAY_AUDIO 
CDROM_PLAY_V AUDIO 

CDROM_PLAY_AUDIO_MSF 

CDROM_PLAY_MSF 

CDROM_PLAY_AUDIO_TI 

CDROM_PLAY_AUDIO_TR 
CDROM JPLAYJTRACK 

CDROM_TOC_HEADER 
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Table 11-2: (continued) 


Structure 

Command 

cd_toc 

CDROM_TOC_ENTRYS 

cd_toc_entry 

CDROM_TOC_ENTRYS 

cd_sub_channel 

CDROM_READ_SUB CHANNEL 

cd_subc_position 

CDROM_READ_SUBCHANNEL 

cd_subc_media_catalog 

CDROM_READ_SUBCHANNEL 

cd_s ubc_isrc_data 

CDROM_READ_SUBCHANNEL 

cd_s ubc_header 

CDROM_READ_SUBCHANNEL 

cd_subc_channel_data 

CDROM_READ_SUBCHANNEL 

cd_subc_information 

CDROM_READ_SUBCHANNEL 

cd_read_header 

CDROM_READ_HEADER 

cd_read_header_data 

CDROM_READ_HEADER 

cd_playback 

CDROM PLAYBACK CONTROL 
CDROM_PLAYBACK_STATUS 


11.2.3.1.1 Structure Used by All SCSI/CAM CDROM/AUDIO I/O Control 
Commands - This section describes the cd_address union that defines the SCSI 
CDROM/AUDIO device Track Address structure and that all the SCSI 
CDROM/AUDIO device I/O control commands use. The SCSI CDROM/AUDIO 
device returns track addresses in either LBA or MSF format. 

union cd_address { 
struct { 

u_char 
u_char 
u_char 
u_char 
} msf; 

struct { 
u_char 
u_char 
u_char 
u_char 
1 lba; 

}; 

/* 

* CD-ROM Address Format Definitions. 

*/ 

#define CDROM_LBA_FORMAT 0 /* Logical Block Address format */ 

#define CDROM_MSF_FORMAT 1 /* Minute Second Frame format */ 

The structure members and their descriptions follow: 

Structure Member Description 

m_units The minute-units binary number of the 

MSF format for CDROM media 


: 8 ; 

m_units; 
s_units; 
f_units; 

/* Minutes/Seconds/Frame format */ 

addr3; 
addr2; 
addrl; 
addrO; 

/* Logical Block Address format */ 
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Structure Member 

Description 

s_units 

The second-units binary number of the 

MSF format for CDROM media 

f_units 

The frame-units binary number of the MSF 
format for CDROM media 

addr3 

The fourth logical block address of LBA 
format for disk media 

addr2 

The third logical block address of LBA 
format for disk media 

addrl 

The second logical block address of LBA 
format for disk media 

addrO 

The first logical block address of LBA 
format for disk media 


11.2.3.1.2 Structure Used by the CDROM_PLAY_AUDIO and 
CDROM PLAY VAUDIO Commands - This section describes the structure that is used by 
"the CDROM_PLAY_AUDIO and CDROM_PLAY_VAUDIO commands. The 
structure is defined as follows: 

struct cd_play_audio { 

u_long pa_lba; /* Logical block address. */ 
u_long pa_length; /* Transfer length in blocks. */ 

1 ; 

The structure members and their descriptions follow: 


Structure Member Description 


pa_lba The LBA where the audio playback 

operation is to begin. 

pa_length The number of contiguous logical blocks to 

be played. 


11.2.3.1.3 Structure Used by the CDROM_PLAY_AUDIO_MSF and 
CDROM PLAY MSF Commands - This section describes the structure that is used by the 
"CDROM_PLAY_AUDIO_MSF and CDROM_PLAY_MSF commands. The 
structure is defined as follows: 


struct cd_play_audio_msf { 

uchar msf_starting_M_unit; 
u_char msf_starting_S_unit; 
u_char msf_starting_F_unit; 
u_char msf_ending_M_unit; 
u_char msf_ending_S_unit; 
u_char msf_ending_F_unit; 

}; 


/* Starting M-unit */ 
/* Starting S-unit */ 
/* Starting F-unit */ 
/* Ending M-unit */ 

/* Ending S-unit */ 

/* Ending F-unit */ 
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The structure members and their descriptions follow: 


Structure Member 

Description 

msf_starting_M_unit 

The minute-unit field of the absolute MSF 
address at which the audio play operation is 
to begin. 

ms f_starting_S_unit 

The second-unit field of the absolute MSF 
address at which the audio play operation is 
to begin. 

ms f_starting_F_unit 

The frame-unit field of the absolute MSF 
address at which the audio play operation is 
to begin. 

ms f_ending_M_unit 

The minute-unit field of the absolute MSF 
address at which the audio play operation is 
to end. 

msf_ending_S_unit 

The second-unit field of the absolute MSF 
address at which the audio play operation is 
to end. 

ms f_ending_F_unit 

The frame-unit field of the absolute MSF 
address at which the audio play operation is 
to end. 


11.2.3.1.4 Structure Used by the CDROM_PLAY_AUDIO_TI Command - This 
section describes the structure that is used by the CDROM_PLAY_AUDIO_TI 
command. The structure is defined as follows: 


/* 

* Define Minimum and Maximum Values 


*/ 

#define CDROM_MIN_TRACK 1 

#define CDROM_MAX_TRACK 99 

#define CDROM_MIN_INDEX 1 

#define CDROM MAX INDEX 99 


for Track & Index. 


/* Minimum 
/* Maximum 
/* Minimum 
/* Maximum 


track number */ 
track number */ 
index value */ 
index value */ 


struct cd_play_audio_ti { 

u_char ti_starting_track; 
u_char ti_starting_index; 
u_char ti_ending_track; 
u_char ti_ending_index; 

}; 


/* Starting track number */ 
/* Starting index value */ 
/* Ending track number */ 

/* Ending index value */ 


The structure members and their descriptions follow: 


Structure Member Description 


ti_starting_track 


ti_starting_index 


ti_ending_track 


The track number at which the audio play 
operation starts. 

The index number within the track at which 
the audio play operation starts. 

The track number at which the audio play 
operation ends. 
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Structure Member 

Description 

ti_ending_index 

The index number within the track at which 
the audio play operation ends. 


11.2.3.1.5 Structure Used by the CDROM_PLAY_AUDIO_TR Command - This 
section describes the structure that is used by the CDROM_PLAY_AUDIO_TR 
command. The structure is defined as follows: 

struct cd_play_audio_tr { 
u_long tr_lba; 
u_char tr_starting_track; 
ushort tr_xfer_length; 


The structure members and their descriptions follow: 

Structure Member Description 

tr_lba The logical block address relative to the 

track being played. A negative value 
indicates a start location within the audio 
pause area at the beginning of the track. 

Track number at which play is to start. 

The number of contiguous logical blocks to 
be output as audio data. 


11.2.3.1.6 Structure Used by the CDROMJTOCJHEADER Command - This section 
describes the structure that is used by the CDROM_TOC_HEADER command. The 
structure is defined as follows: 

struct cd_toc_header { 

u_char th_data_lenl; 
u_char th_data_lenO; 
u_char th_starting_track; 
u_char th_ending_track; 


The structure members and their descriptions follow: 

Structure Member Description 

th_data_lenl The total number of bytes in the table of 

contents for MSF format. 

th_data_lenO The total number of bytes in the table of 

contents for LBA format. 

th_starting_track Starting track number for which data is to 

be returned. If the value is 0 (zero), data is 
to be returned starting with the first track on 
the medium. 


/* TOC data length MSB */ 

/* TOC data length LSB */ 

/* Starting track number */ 
/* Ending track number */ 


tr_starting_track 

tr_xfer_length 


/* Track relative LBA */ 

/* Starting track number */ 
/* Transfer length */ 
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Structure Member 

Description 

th_ending_track 

The track number at which the audio play 
operation ends. 


11.2.3.1.7 Structures Used by the CDROM_TOC_ENTRYS Command - This section 
describes the structures that are used by the CDROM_TOC_ENTRYS command. 

The structures are defined as follows: 

struct cd_toc { 

u_char toc_address_format; 
u_char toc_starting_track; 
u_short toc_alloc_length; 
caddr_t toc_buffer; 


The structure members and their descriptions follow: 

Structure Member Description 

toc_address_format The address format, LBA or MSF. 

toc_starting_track The track number at which the audio play 

operation starts. 

toc_alloc_length The allocation length of the table of 

contents buffer in bytes 

toc_buf f er A pointer to the TOC buffer. 


struct cd_toc_entry { 


u_char 



8; 

/* 

Reserved */ 

u_char 

te 

control : 

4; 

/* 

Control field (attributes) */ 

u_char 

te_ 

_addr_type : 

4; 

/* 

Address type information */ 

u_char 

te_ 

_track_number; 


/* 

The track number */ 

u_char 



8; 

/* 

Reserved */ 


union cd_address te_absaddr; /* Absolute CD-ROM Address */ 
J; 

The structure members and their descriptions follow: 

Structure Member Description 

te_control The control field containing attributes. The 

possible settings follow: 

Bit No. Set to 0 (Zero) Set to 1 

0 Audio without Audio with preemphasis 

preemphasis 

1 Digital copy prohibited Digital copy permitted 

2 Audio track Data track 

3 Two-channel audio Four-channel audio 
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/* Address format to return */ 
/* Starting track number */ 

/* Allocation length */ 

/* Pointer to TOC buffer */ 












te_addr_type Address-type infoimation, MSF or LB A 

te_track_number The current track number that is being 

played. 

te_absaddr The absolute address of the audio track, 

MSF or LBA format. 


11.2.3.1.8 Structures Used by the CDROM_READ_SUBCHANNEL Command - 

The CDROM_READ_SUBCHANNEL command requests subchannel data and the 
state of audio play operations from the target device. This section describes the 
structure that is used by the CDROM_READ_SUBCHANNEL command. The 
structure is defined as follows: 

/* 

* CD-ROM Sub-Channel Q Address Field Definitions. 

*/ 

#define CDROM_NO_INFO_SUPPLIED 0x0 /* Information not supplied */ 

#define CDROM_CURRENT_POS_DATA 0x1 /* Encodes current position data */ 

^define CDROM_MEDIA_CATALOG_NUM 0x2 /* Encodes media catalog number */ 

^define CDROM_ENCODES_ISRC 0x3 /* Encodes ISRC */ 

/* ISRC=International-Standard- */ 

/* Recording-Code */ 

/* Codes 0x4 through 0x7 are Reserved */ 

/* 

* CD-ROM Data Track Definitions 

V 

ffdefine CDROM_AUDIO_PREMPH 0x01 /* 0/1 = Without/With Pre-emphasis */ 

#define CDROM_COPY_PERMITTED 0x02 /* 0/1 = Copy Prohobited/Allowed */ 

^define CDROM_DATA_TRACK 0x04 /* 0 - Audio, 1 = Data track */ 

^define CDROM_FOUR_CHAN_AUDIO 0x10 /* 0 = 2 Channel, 1=4 Channel */ 

/* 

* Sub-Channel Data Format Codes 
*/ 

^define CDROM_SUBQ_DATA 0x00 /* Sub-Channel data information */ 

^define CDROM_CURRENT_POSITION 0x01 /* Current position information */ 

^define CDROM_MEDIA_CATALOG 0x02 /* Media catalog number */ 

^define CDROM_ISRC 0x03 /* ISRC information */ 

/* ISRC=International-Standard- */ 

/* Recording-Code */ 

/* Codes 0x4 through OxEF are Reserved */ 

/* Codes OxFO through OxFF are Vendor Specific */ 

/* 

* Audio Status Definitions returned by Read Sub-Channel Data Command 

V 

^define AS_AUDIO_INVALID 0x00 /* Audio status not supported */ 

^define AS_PLAY_IN_PROGRESS 0x11 /* Audio play operation in prog */ 

^define AS_PLAY_PAUSED 0 x 12 /* Audio play operation paused */ 

#define AS_PLAY_COMPLETED 0x13 /* Audio play completed */ 

#define AS_PLAY_COMPLETED 0x13 /* Audio play completed */ 

^define AS_PLAY_ERROR 0x14 /* Audio play stopped by error */ 

^define AS_NO_STATUS 0x15 /* No current audio status */ 

struct cd_sub_channel { 

u_char sch_address_format; /* Address format to return */ 

u_char sch_data_format; /* Sub-channel data format code */ 

u_char sch_track_number; /* Track number */ 

u_short sch_alloc_length; /* Allocation length */ 

caddr_t sch_buffer; /* Pointer to SUBCHAN buffer */ 
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} ; 


The structure members and their descriptions follow: 


Structure Member 

Description 

sch_addres s_format 

The address format, LBA or MSF. 

sch_data_format 

The type of subchannel data to be returned. 

sch_track_number 

The track from which ISRC data is read. 

sch_alloc_length 

The allocation length of the table of 
contents buffer in bytes 

sch_buffer 

A pointer to the SUBCHAN buffer defined 
by the sch_data_format member. 


struct cd_subc_position { 

u_char scp_data_format; 
u_char scp_control : 4 ; 

u_char scp_addr_type : 4; 

u_char scp_track_number; 
u_char scp_index_number; 
union cd_address scp_absaddr; 
union cd_address scp_reladdr; 

}; 

#define scp_absmsf scp_absaddr.msf 
#define scp_abslba scp_absaddr.lba 
#define scp_relmsf scp_reladdr.msf 
#define scp_rellba scp_reladdr.lba 


/* Data Format code */ 

/* Control field (attributes) */ 
/* Address type information */ 

/* The track number */ 

/* The index number */ 

/* Absolute CD-ROM Address */ 

/* Relative CD-ROM Address */ 


The structure members and their descriptions follow: 


Structure Member Description 


Data format code. 

The control field containing attributes. The 
possible settings follow: 


scp_data_format 
scp_control 

Bit No. 

0 

1 

2 

3 


Set to 0 (Zero) 

Audio without 
preemphasis 

Digital copy prohibited 
Audio track 
Two-channel audio 


Set to 1 

Audio with preemphasis 

Digital copy permitted 
Data track 
Four-channel audio 


scp_addr_type Address-type information, MSF or LBA 

format. The address format, LBA or MSF. 

scp_track_number The current track number that is being 

played. 

scp_index_number The index number within an audio track. 
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scp absaddr The absolute address of the audio track, 

MSF or LBA format. 

scp reladdr The CDROM address relative to the track 

being played. 


struct cd_subc_media_catalog { 

u_char smc_data_format; 


u_char : 8; 

u_char : 8; 

u_char : 8; 

u_char : 7, 

smc_mc_valid : 1; 


u_char smc_mc_number[15]; 


/* Data Format code */ 

/* Reserved */ 

/* Reserved */ 

/* Reserved */ 

/* Reserved */ 

/* Media catalog valid 1 «= True */ 
/* Media catalog number ASCII */ 


The structure members and their descriptions follow: 


Structure Member Description 


smc_data_format 
smc_mc_val id 
smc me number 


Data format code. 

Media catalog number is valid. 
Media catalog number. 


struct cd_subc_isrc_data { 


u_char 

sid_data_format; 


/* 

Data Format code 

*/ 

u_char 


8; 

/* 

Reserved */ 


u_char 

sid_track_number; 


/* 

The track number 

V 

u_char 


8; 

/* 

Reserved */ 


u_char 


1 , 

/* 

Reserved */ 



sidtevalid : 

1; 

/* 

Track code valid, 

1 - True 

u_char 

sid_tc_number[15] 


/* 

/* 

International-Standard- */ 
Recording-Code (ASCII) *, 


The structure members and their descriptions follow: 


Structure Member Description 


sid_data_format 

Data format code. 

sid_track_number 

The current track number at which ISRC is 
located. 

sid_tc_valid 

The track code is valid. 

sid_tc_number[15] 

The track code number. 


struct cd_subc_header { 

u_char : 8; 

u_char sh_audio_status; 
u_char sh_data_lenl; 
u_char sh_data_lenO; 


/* Reserved */ 

/* Audio status */ 

/* Sub-Channel Data length MSB */ 
/* Sub-Channel Data length LSB */ 
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The structure members and their descriptions follow: 


Structure Member Description 


sh_audio_status 

The audio status code. 

sh_data_lenl 

The subchannel data length for MSF 
format. 

sh_data_lenO 

The subchannel data length for LBA 
format. 

struct cd_subc_channel 
struct cd_subc 
struct cd_subc 
struct cd_subc 
struct cd subc 
J; 

data { 

header scdheader; 

_position scd_position_data; 
_media_catalog scd__media_catalog; 
_isrc_data scd_isrc_data; 

The structure members and their descriptions follow: 

Structure Member 

Description 

scd_header 

The subchannel data header, which is four 
bytes. 

scd_position_data 

CDROM current-position data information. 

scd_media_catalog 

The Media Catalog Number data 
information. 

scd_isrc_data 

Track International-Standard-Recording- 
Code (ISRC) data information. 


struct cd_subc_information { 

struct cdsubcheader sci_header; 
union { 

struct cd_subc_channel_data sci_channel_data; 
struct cd_subc_position sci_position_data; 
struct cd_subc_media_catalog sci_media_catalog; 
struct cd_subc_isrc_data sci_isrc_data; 

} scidata; 

}; 


#define sci_scd 
#define sci_scp 
#define sci_smc 
#define sci sid 


sci_data.sci_channel_data 
sci_data.sci_position_data 
sci_data.sci_media_catalog 
sci data.sci isrc data 


#define CDROM_DATA_MODE_ZERO 0 

#define CDROM_DATA_MODE_ONE 1 

#define CDROM_DATA_MODE_TWO 2 

/* Modes 0x03-OxFF are reserved. */ 


/* All bytes zero */ 

/* Data mode one format */ 
/* Data mode two format */ 


This structure is used to allocate data space. The structure members and their 
descriptions follow: 


Structure Member Description 
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Structure Member 

Description 


sci_channel_data 
sci_position_data 
sci_media_catalog 
sci_isrc_data 

Space for channel data. 

Space for current position data. 

Space for Media Catalog data. 

Space for ISRC data. 


11.2.3.1.9 Structures Used by the CDROM_READ_HEADER Command - This 
section describes the structures that are used by the CDROM_READ_HEADER 
command. The structures are defined as follows: 

struct cd_read_header [ 

u_char rh_address_format; 
u_long rh_lba; 
u_short rh_alloc_length; 
caddr_t rh_buffer; 

}; 


The structure members and their descriptions follow: 


Structure Member 

Description 

rh_address_format 
rh_lba 

rh_alloc_length 
rh_buffer 

The address format, LBA or MSF. 

The logical block address for LBA format. 
The allocation length of the header buffer. 

A pointer to the header buffer. 


/* Address format to return */ 
/* Logical block address */ 

/* Allocation length */ 

/* Pointer to header buffer */ 


struct cd_read_header_data { 


u_char rhd_data 

mode; 


/* 

CD-ROM data mode */ 

u_char 


: 8; 

/* 

Reserved */ 

u_char 


: 8; 

/* 

Reserved */ 

u_char 


: 8; 

/* 

Reserved */ 

union cd_address 

rhd_absaddr; 

/* 

Absolute CD-ROM address */ 


^define rhd_msf rhd_absaddr.msf 
#define rhd_lba rhd absaddr.lba 


The structure members and their descriptions follow: 


Structure Member 

Description 

rhd_data_mode 

The CDROM data mode type. 

rhd_absaddr 

The absolute address of the audio track, 

MSF or LBA format. 
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11.2.3.1.10 Structure Used by the CDROM_PLAY_TRACK Command - This section 
describes the structure that is used by the CDROM_PLAY_TRACK command. The 
structure is defined as follows: 

struct cd_play_track { 

u_char pt_starting_track; /* Starting track number */ 

u_char pt_starting_index; /* Starting index value */ 

u_char pt_number_indexes; /* Number of indexes */ 


The structure members and their descriptions follow: 


Structure Member Description 


pt_starting_track The track number at which the audio play 

operation starts. 

pt_starting_index The index number within the track at which 

the audio play operation starts. 

pt_number_indexes The number of index values in the audio 

encoding on CDROM media. 


11.2.3.1.11 Structure Used by the CDROM_PLAYBACK_CONTROL and 
CDROM PLAYBACK STATUS Commands - This section describes the structures that are 
“used by the CDROM_PLAYBACK_CONTROL and 
CDROM_PLAYBACK_STATUS commands. The structures are defined as follows: 

/* 

* Definitions for Playback Control/Playback Status Output Selection 


Codes */ 

#define CDROM_MIN_VOLUME 

0x0 

/* 

Minimum volume level */ 

#define CDROM_MAX_VOLUME 

OxFF 

/* 

Maximum volume level */ 

#define CDROM_PORT_MUTED 

0x0 

/* 

Output port is muted */ 

#define CDROM_CHANNEL_0 

0x1 

/* 

Channel 0 to output port */ 

#define CDROM_CHANNEL_l 

0x2 

/* 

Channel 1 to output port */ 

#define CDROM_CHANNEL_0_1 

0x3 

/* 

Channel 0 & 1 to output port */ 

struct cd_playback { 

u_jshort pb_alloc_length; 


/* 

Allocation length */ 

caddr_t pb_buffer; 


/* 

Pointer to playback buffer */ 


}; 


The structure members and their descriptions follow: 


Structure Member 

Description 

pb_alloc_length 
pb_buffer 

Allocation length of the playback buffer. 

A pointer to the playback buffer. 
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11.2.3.1.12 Structure Used by the CDROM_PLAYBACK_CONTROL Command - 

This section describes the structure that is used by the 

CDROM_PLAYBACK_CONTROL command. The structure is defined as follows: 

struct cd_playback_control { 

u_char pc_reserved[10]; 
u_char pc_chanO_select : 

u_char pc_chanO_volume; 
u_char pc_chanl_select : 

uchar pc_chanl_volume; 
u_char pc_chan2_select : 

u_char pc_chan2_volume; 
u_char pc_chan3_select : 

u_char pc_chan3_volume; 

}; 


The structure members and their descriptions follow: 


Structure Member 

Description 

pc_chan0_select 

The selection code for Channel 0. The low 
four bits are reserved. 

pc_chan0_volume 

The volume level value for Channel 0. 

pc_chanl_select 

The selection code for Channel 1. The low 
four bits are reserved. 

pc_chanl_volume 

The volume level value for Channel 1. 

pc_chan2_select 

The selection code for Channel 2. The low 
four bits are reserved. 

pc_chan2_volume 

The volume level value for Channel 2. 

pc_chan3_select 

The selection code for Channel 3. The low 
four bits are reserved. 

pc_chan3_volume 

The volume level value for Channel 3. 


4, 

4; 

4, 

4; 

4, 

4; 

4, 

4; 


/* Reserved 
/* Channel 0 
/* Reserved 
/* Channel 0 
/* Channel 1 
/* Reserved 
/* Channel 1 
/* Channel 2 
/* Reserved 
/* Channel 2 
/* Channel 3 
/* Reserved 
/* Channel 3 


'/ 

selection code */ 
'/ 

volume level */ 
selection code */ 
'/ 

volume level */ 
selection code */ 
'/ 

volume level */ 
selection code */ 

V 

volume level */ 


11.2.3.1.13 Structure Used by the CDROM_PLAYBACK_STATUS Command - 

This section describes the structure that is used by the 

CDROMJPLAYBACK_STATUS command. The structure is defined as follows: 


/* 

* Audio status return by Playback Status Command. 


V 

#define PS_PLAY_IN_PROGRESS 0x00 
#define PS_PLAY_PAUSED 0x01 
#define PS_MUTING_ON 0x02 
#define PS_PLAY_COMPLETED 0x03 
#define PS PLAY ERROR 0x04 


Hdefine PS_PLAY_NOT_REQUESTED 0x05 


/* Audio Play Oper In Progess */ 

/* Audio Pause Oper In Progress */ 
/* Audio Muting On */ 

/* Audio Play Oper Completed */ 

/* Error Occurred During Play */ 

/* Audio Play Oper Not Requested */ 


/* 

* Data structure returned by Playback Status Command. 
*/ 

struct cd_playback_status { 

u_char : 8; /* Reserved */ 
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u_char 

ps_lbamsf 

: 1, 

/* 

Address format 0/1 = LBA/MSF ■ 



: 7; 

/* 

Reserved */ 

u_char 

ps_data_lenl; 


/* 

Audio data length MSB */ 

u_char 

ps_data_lenO; 


/* 

Audio data length LSB */ 

u_char 

ps_audio_status; 


/* 

Audio status */ 

u_char 

ps_control 

: 4, 

/* 

Control field (attributes) */ 



: 4; 

/* 

Reserved */ 

union cdaddress psabsaddr; 

/* 

Absolute CD-ROM address */ 

u_char 

ps_chanO_select 

: 4, 

/* 

Channel 0 selection code */ 



: 4; 

/* 

Reserved */ 

u_char 

ps_chanO_volume; 


/* 

Channel 0 volume level */ 

u_char 

ps_chanl_select : 

: 4, 

/* 

Channel 1 selection code */ 



: 4; 

/* 

Reserved */ 

u_char 

ps_chanl_volume; 


/* 

Channel 1 volume level */ 

uchar 

ps_chan2_select : 

: 4, 

/* 

Channel 2 selection code */ 



: 4; 

/* 

Reserved */ 

u_char 

ps_chan2_volume; 


/* 

Channel 2 volume level */ 

u_char 

ps_chan3_select : 

: 4, 

/* 

Channel 3 selection code */ 



: 4; 

/* 

Reserved */ 

u_char 

ps_chan3_volume; 


/* 

Channel 3 volume level */ 


The structure members and their descriptions follow: 


Structure Member Description 


The address format: a 0 (zero) means LBA; 
a 1 means MSF. 

The audio data length if the address format 
is MSF. 

The audio data length if the address format 
is LBA. 

The audio status 

The control field containing attributes. The 
possible settings follow: 


ps_lbamsf 

ps_data_lenl 

ps_data_lenO 

ps_audio_status 

ps_control 

Bit No. 

0 

1 

2 


Set to 0 (Zero) 

Audio without 
preemphasis 

Digital copy prohibited 
Audio track 
Two-channel audio 


Set to 1 

Audio with preemphasis 

Digital copy permitted 
Data track 
Four-channel audio 


ps_absaddr 

ps_chanO_select 

ps_chanO_volume 

ps_chanO_select 

ps_chanl_volume 


The low four bits are reserved. 

The absolute address of the audio track, 
MSF or LBA format. 

The selection code for Channel 0. The low 
four bits are reserved. 

The volume level setting for Channel 0. 

The selection code for Channel 0. The low 
four bits are reserved. 

The volume level setting for Channel 1. 
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ps_chanl_select 

ps_chan2_volume 

ps_chan2_select 

ps_chan3_volume 


The selection code for Channel 1. The low 
four bits are reserved. 

The volume level setting for Channel 2. 

The selection code for Channel 2. The low 
four bits are reserved. 

The volume level setting for Channel 3. 


11.3 Adding a Programmer-Defined SCSI/CAM Device 

The procedure for installing device drivers described in Guide to Writing and Porting 
VMEbus and TURBOchannel Device Drivers applies to adding SCSI/CAM peripheral 
device drivers to your system. Follow that procedure after completing the entries to 
the SCSI/CAM-specific structures described in this chapter and in Chapter 3. 
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SCSI/CAM Special I/O Interface 



This chapter describes the SCSI/CAM special I/O interface. The USCA software 
includes an interface developed to process special SCSI I/O control commands used 
by the existing Digital SCSI subsystem and to aid in porting new or existing SCSI 
device drivers from other vendors to the USCA. 

Application programs issue I/O control commands using the ioctl system call to 
send special SCSI I/O commands to a peripheral device. The term “special” refers to 
commands that are not usually issued to the device through the standard driver entry 
points. SCSI device drivers usually require the special I/O control commands in 
addition to the standard read and write system calls. With the SCSI/CAM 
special I/O interface, SCSI/CAM peripheral driver writers do not need detailed 
knowledge of either the system-specific or the CAM-specific structures and routines 
used to issue a SCSI command to the CAM I/O subsystem. 

12.1 Application Program Access 

Application programs access the SCSI/CAM special I/O interface by making requests 
to peripheral drivers using the ioctl system call. This system call is processed by 
system kernel support routines that invoke the device driver’s I/O control command 
entry point in the character device switch table defined in the 
machine/common/conf . c file. The device driver’s I/O control routine accesses 
the special I/O interface using either the supplied SCSI/CAM peripheral common 
routine, ccmn_DoSpecialCmd, or a driver-specific routine. Figure 12-1 shows the 
flow of application program requests through the operating system to the SCSI/CAM 
special I/O interface and the CAM I/O subsystem. 



Figure 12-1: Application Program Flow Through SCSi/CAM Special I/O 
Interface 


Application Program Interface 
Issues I/O Control System Call via 
int ioctl (int fd, int cmd ,char *data) 



_Z_ 

CAM Peripheral Driver I/O Control 
Command Entry Point Entered via 
int xxiocti (devj dev, int cmd, caddr_t data, int flags) 


Invoke Peripheral Common Routine via 
int ccmn Dospeciaicmd (dev_t dev, int cmd, caddrj data 
int flags, CCB_SCSIIO *ccb, int sflags) 


± 


Invoke SCSI Special I/O Command 
Processing Entry Point 
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12.2 Device Driver Access 

SCSI/CAM peripheral device drivers access the SCSI/CAM special I/O interface 
using either the supplied SCSI/CAM peripheral common routine, 
ccmn_SysSpecialCmd, or using a driver-specific routine. Figure 12-2 shows the 
flow of system requests from device drivers through the SCSI/CAM special I/O 
interface and the CAM I/O subsystem. 
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Figure 12-2: Device Driver Flow Through SCSI/CAM Special I/O 
Interface 
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12.3 SCSI/CAM Special Command Tables 

The SCSI/CAM special I/O interface includes default command tables that provide 
backwards compatibility with existing SCSI I/O control commands. The following 
predefined SCSI/CAM Special Command Tables are included: 

• cam GenericCmds 
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• cam_DirectCmds 

• cam_AudioCmds 

• cam_SequentialCmds 

• cam_MtCmds 

The interface also allows commands to be added to the existing command tables and 
new command tables to be added. The SCSI/CAM special I/O interface includes 
routines that manipulate the tables so programmers can write device drivers to easily 
add and remove command tables. 

The command table header structure, SPECIAL_HEADER, provides a bit mask of 
device types that can be used with a command table. The Special Command Header 
Structure is defined as follows: 

/* 

* Special Command Header Structure: 

*/ 


typedef struct special_header { 

struct special_header *sph_flink; 
struct special_header *sph_blink; 
struct special_cmd *sph_cmd_table; 
u_long sph_device_type; 
u_long sph_table_flags; 
caddr_t sph_table_name; 

} SPECIAL_HEADER; 


/* Forward link to next table */ 
/* Backward link to prev table */ 
/* Pointer to command table */ 

/* The device types supported */ 
/* Flags to control cmd lookup */ 
/* Name of this command table */ 


12.3.1 The sph_flink and sph_blink Members 

These are table-linkage members that allow command tables to be dynamically added 
or removed from the list of tables searched by the SCSI/CAM special I/O interface 
when processing commands. 

12.3.2 The sph_cmd_table Member 

A pointer to the Special Command Entry Structure. 

12.3.3 The sph_device_type Member 

The device types supported by this SCSI/CAM Special Command Table. 

12.3.4 The sph_table_flags Member 

The SPH_SUB_COMMAND, which indicates that the command table contains 
subcommands. 

12.3.5 The sph_table_name Member 

The name of this SCSI/CAM Special Command Table. 
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12.4 SCSI/CAM Special Command Table Entries 

Each SCSI/CAM Special Command Table contains multiple entries. Each entry 
provides enough information to process the command associated with that entry. The 
command tables can be dynamically added, but the entries within the command 
tables are not dynamic. Each command table’s entries are statically defined so that 
individual entries cannot be appended to the table. The Special Command Entry 
Structure structure is defined as follows: 

/* 

* Special Command Entry Structure: 

V 

typedef struct special_cmd { 

int spc_ioctl_cmd; 

in t s pcs ub_comma nd; 

u_cha r s pc_cmd_flags; 
u_char spc_cmd_code; 
u_short : 16; 

u_long spc_device_type; 
u_long spc_cmd_parameter; 
u_long spc_cam_flags; 
u_long spc_file_flags; 
int spc_data_length; 
int spc_timeout; 

int (*spc_docmd)(); 

int (*spc_mkcdb)(); 

int (*spc_setup){); 

caddr_t spc_cdbp; 
caddr_t spc_cmdp; 

} SPECIAL_CMD; 


12.4.1 The spcJoctl_cmd and spc_sub_command Members 

These members contain the SCSI I/O control command code and subcommand used 
to locate the appropriate table entry. The subcommand is checked only if flags are 
set that indicate a subcommand exists. 


/* The I/O control command code */ 
/* The I/O control sub-command */ 
/* The special command flags */ 

/* The special command code */ 

/* Unused ... align next field */ 
/* The device types supported */ 

/* Command parameter (if any) */ 

/* The CAM flags field for CCB */ 
/* File control flags (fcntl) */ 

/* Kernel data buffer length */ 

/* Timeout for this command */ 

/* Function to do the command */ 

/* Function to make SCSI CDB */ 

/* Setup parameters routine */ 

/* Pointer to prototype CDB */ 

/* Pointer to the command name */ 


12.4.2 The spc_cmd_flags Member 

This member contains flags to control the action of the SCSI/CAM special I/O 
interface routines. The flag definitions are described in the following table: 


Flag Name 

Description 

SPC_SUSER 

Restricted to superuser. 

SPC_COPYIN 

User buffer to copy from. 

SPC_COPYOUT 

User buffer to copy to. 

SPC_NOINTR 

Do not allow sleep interrupts. 

S PC_DATA_IN 

Data direction is from device. 

S PC_DATA_OUT 

Data direction is to device. 

SPC_DATA_NONE 

No data movement for command. 

SPC_SUB_COMMAND 

Entry contains subcommand. 

SPC_INOUT 

Copy in and out. 

SPC_DATA_INOUT 

Copy data in and out. 
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12.4.3 The spc.command.code Member 

This member contains the special SCSI opcode used to execute this command. This 
member is used during the creation of the CDB. 

12.4.4 The spc.device.type Member 

This member defines the specific device types with which this command is used. For 
example, direct-access and readonly direct-access devices share many of the same 
commands. Therefore, rather than duplicating command table entries, both device 
types can use the same command table. The values that are valid for this member are 
those defined in the Inquiry data device type member of the inquiry inf o 
structure, which is defined in the /usr/sys/h/scsi_all. h file. 

12.4.5 The spc_cmd_parameter Member 

This member is used to define any special parameters used by the command. For 
example, the SCSI START CDB command, which is defined in the 
/usr/sys/h/scsi_direct. h file, is used for stopping, starting, and ejecting a 
CDROM caddy. The parameter member can be defined as the subcommand code so 
a common routine can be used to create the CDB. 

12.4.6 The spc.cam .flags Member 

This member contains the CAM flags necessary for processing the command. The 
CAM flags are defined in the file /usr/sys/h/cam. h. 

12.4.7 Thespc.file.flagsMember 

This member contains the file access bits required for accessing the command. For 
example, the command can be restricted to device files opened for read and write 
access. The file flags are defined in the file /usr/sys/h/f ile. h. 

12.4.8 The spc.data .length Member 

This member describes the length of the buffer to hold additional kernel data that is 
required to process the command. Usually, this member is set to 0 (zero), since the 
data buffer lengths are normally decoded from the I/O command code or taken from a 
member in the I/O parameter buffer. 

12.4.9 The spc.timeout Member 

This member defines the default timeout for this command. This value is used for 
the SCSI I/O CCB timeout member, unless it is overridden by the timeout member in 
the Special I/O Argument Structure. 

12.4.10 The spc.docmd Member 

This member specifies the routine to invoke to execute the command. A routine is 
required by I/O commands that need special servicing. For example, if the I/O 
command does not return all the data read by the SCSI command, then a routine is 
needed to handle this special servicing. 
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12.4.11 The spcjnkcdb Member 

This member specifies the routine that is invoked to create the CDB for the 
command. A routine is not necessary for simple commands, such as TEST UNIT 
READY. However, any command that requires additional members to be set up in 
the CDB prior to issuing the SCSI command must define this routine. 


12.4.12 The spc.setup Member 

This member is required by any command that has special setup requirements. For 
example, commands that pass a user buffer and length as part of the I/O parameters 
buffer structure must have a setup routine to copy these members to the Special I/O 
Argument Structure. This applies to all previously defined commands, but does not 
apply to commands implemented using the new SCSIJSPECIAL I/O control 
command code. 


12.4.13 The spc_cdbp Member 

This member is used by commands that can be implemented using a prototype CDB. 
A prototype CDB is a SCSI command that can be implemented using a statically 
defined SCSI CDB. Fields within the CDB do not change. Usually, simple SCSI 
commands, such as SCSI_START_UNIT, can be implemented with a prototype CDB 
so that the make CDB routine is not required. 

12.4.14 The spc_cmdp Member 

This member points to a string that describes the name of the command. This string 
is used during error reporting and during debugging. 


12.4.15 Sample SCSI/CAM Special Command Table 

The example that follows shows a sample SCSI/CAM Special Command Table with 
one entry defined: 


#include 

#include 

#include 


./h/cdrom.h" 
./h/mtio.h" 
./h/rzdisk.h" 


#include 

#include 

#include 

#include 

#include 

#include 

#include 

#include 


./h/cam.h" 

./h/cam_special.h" 
./h/dec_cam.h" 
./h/scsi_all.h" 
./h/scsi_direct.h" 
./h/scsi_rodirect.h" 
./h/scsi_sequential.h" 
./h/scsi_special.h" 


extern int scmnMakeFormatUnit(), scmnSetupFormatUnit(); 


/* 

* Command Header for Direct-Access Command Table: 
*/ 

struct special_header cam_DirectCmdsHdr = { 


(struct special_header *) 0, /* 
(struct special_header *) 0, /* 
cam_DirectCmds, /* 
(BM(DTYPE_DIRECT) | BM(DTYPE_RODIRECT)),/* 
0 , /* 
"Direct Access Commands" /* 

1 ; 


sph_flink */ 
sph_blink */ 
sphcmdtable */ 
sph_device_type */ 
sph_table_flags */ 
sph_table_name */ 
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★ * 

* Special Direct Access Command Table * 

* * 




struct specialcmd cam_DirectCmds[] = { 
{ SCSI_FORMAT_UNIT, 

0 , 

(SPC_COPYIN | SPC_DATA_OUT), 
DIR_FORMAT_OP , 

BM(DTYPE_DIRECT), 

0 , 

CAMDIROUT, 

FWRITE, 

“ 1 / 

(60 * ONEMINUTE), 

(int (*)()) 0, 
scmn_MakeFormatUnit, 
scmn_SetupFormatUnit, 

(caddr_t) 0, 

"format unit" 

}, 


/* spc_ioctl_cmd */ 

/* spc_sub_command */ 

/* spc_cmd_flags */ 

/* spc_cmd_code */ 

/* spc_device_type */ 

/* spc_cmd_parameter */ 
/* spc_cam_flags */ 

/* spc_file_flags */ 

/* spc_data_length */ 

/* spc_timeout */ 

/* spc_docmd */ 

/* spc_mkcdb */ 

/* spc_setup */ 

/* spc_cdbp */ 

/* spc_cmdp */ 


{ END_OF_CMD_TABLE } /* End of cam_DirectCmds[] Table. */ 

} ; 

/* 

* Define Special Commands Header & Table for Initialization Routine. 
*/ 

struct special_header *cam_SpecialCmds = &cam_SpecialCmdsHdr; 

struct special_header *cam_SpecialHdrs[] = 

{ &cam_GenericCmdsHdr, &cam_DirectCmdsHdr, &cam_AudioCmdsHdr, 
&cam_SequentialCmdsHdr , &cam_MtCmdsHdr , 0 ]; 


12.5 SCSI/CAM Special I/O Argument Structure 

A Special I/O Argument Structure is passed to the SCSI/CAM special I/O interface 
to control processing of the I/O control command being executed. The structure 
members provide information to process a special command for different SCSI 
subsystems. Default settings and routines invoked by the SCSI/CAM special I/O 
interface can be overridden by the calling routine. Table 12-1 shows the members 
that are mandatory for the calling routine to set up, the members that are optional, 
and the members that are used or filled in by the SCSI/CAM special I/O interface: 


Table 12-1: SCSI/CAM Special I/O Argument Structure 


Member Name 

Type 

Description 

u_long sa_flags; 

M 

Flags to control command 

dev_t sa_dev; 

M 

Device major/minor number 

u_char sa_unit; 

U 

Device logical unit number 

u_char sa_bus; 

M 

SCSI host adapter bus number 

u_char sa_target; 

M 

SCSI device target number 

u_char sa_lun; 

M 

SCSI logical unit number 

int sa ioctl cmd; 

M 

The I/O control command 
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Table 12-1: (continued) 


Member Name 

Type 

Description 

int sa_ioctl_scmd; 

C 

The subcommand, if any 

caddr_t sa_ioctl_data; 

C 

The command data pointer 

caddr_t sa_device_name; 

M 

Pointer to the device name 

int sa_device_type; 

M 

The peripheral device type 

int sa_iop_length; 

I 

Parameters’ buffer length 

caddr_t sa_iop_buffer; 

I 

Parameters’ buffer address 

int sa_file_flags; 

M 

The file control flags 

int sa_sense_length; 

O 

Sense data buffer length 

u_char sa_sense_resid; 

I 

Sense data residual count 

caddr_t sa_sense_buffer; 

0 

Sense data buffer address 

int sa_user_length; 

I 

User data buffer length 

caddr_t sa__user_buf fer; 

I 

User data buffer address 

struct buf *sa_bp; 

0 

Kernel I/O request buffer 

CCB_SCSIIO *sa_ccb; 

o 

CAM control block buffer 

struct special_cmd *sa_spc; 

I 

Special command table entry 

struct special_header *sa_sph; 

0 

Special command table header 

u_long sa_cmd_parameter; 

I 

Command parameter, if any 

int (*sa_error)(); 

0 

The error report routine 

int (*sa_start)(); 

o 

The driver start routine 

int sa_data_length; 

I 

Kernel data buffer length 

caddr_t sa_data_buffer; 

I 

Kernel data buffer address 

caddr_t sa_cdb_pointer; 

I 

Pointer to the CDB buffer 

u_char sa_cdb_length; 

I 

Length of the CDB buffer 

u_char sa_cmd_flags; 

I 

The special command flags 

u_char sa_retry_count; 

I 

The current retry count 

u_char sa_retry_limit; 

o 

Times to retry this command 

int sa_timeout; 

0 

Timeout for this command 

int sa_xfer_resid; 

I 

Transfer residual count 

caddr_t sa_specific; 

0 

Driver-specific information 


Legend: M - Mandatory. Must be set up by the caller. 

C - Command Dependent. Depends on special command. 

O ■ Optional. Optionally overrides defaults. 

I «Interface. Used or filled in by SCSI/CAM special I/O interface. 
U - Unused. Not used by SCSI/CAM special 1/0 interface. 


Several of the members marked as mandatory in Table 12-1 are set up initially by the 
routine that allocates the Special I/O Argument Structure. The following members 
are initialized by the allocation routine: sa_bus; sa_target; sa_lun; 
sa_unit (same as target); sa_retry_limit (set to 30); and sa_start (set to 
xpt_action). 
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12.5.1 


12.5.2 


Fields that are identified as optional in Table 12-1 can be defined by the caller to 
override some of the defaults used by the SCSI/CAM special I/O interface. The 
following table describes the defaults used by the SCSI/CAM special I/O interface: 


Member Name 

Default 

sa_sense_length 

Set to DEC_AUTO_SENSE_SIZE, 
which is defined in 
/usr/sys/h/dec_cam.h. 

sa_sense_buf fer 

Sense buffer in SCSI/CAM 
Peripheral Device Driver Working 
Set Structure. 

sa_bp 

Allocated as needed for data 
movement commands. 

sa_ccb 

Allocated by the CAM 
xpt_ccb_alloc routine. 

sa_error() 

Special interface error report 
routine. 

sa_start() 

Uses the CAM xpt_action 
routine. 

sa_timeout 

Uses the timeout value from the 
SCSI/CAM Special Command 
Table entry. 

sa_speci£ic 

Is not set up or used by 

SCSI/CAM special I/O interface. 

The sa_flags Member 


This member is used to control the actions of the SCSI/CAM special I/O interface. 
The low order five bits of this member can be set by the calling routine. All other 
bits in this member are reserved. The table that follows shows the control flags that 
can be set by the calling routine: 

Flag Name 

Description 

SA_N°_ERROR_ RE COV E RY 

Do not perform error recovery. 

SA_NO_ E RROR_LOGGING 

Do not log error messages. 

SA _ N0 _ SLEEP _ INTR 

Do not allow sleep interrupts. 

SA_NO_SIMQ_T H AW 

Leave SIM queue frozen on errors. 

SA_NO_WAIT_FOR_IO 

Do not wait for I/O to complete. 


The sa_dev Member 

This member contains the device major/minor number pair passed into the device 
driver routines. It is used to fill in the bp dev member of the system I/O request 
member. 
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12.5.3 The sa.unit, sa_bus, sa_target, and sajun Members 

These members are used to address the SCSI device to which the command is being 
sent. The sa_unit member is not used, but has been included for device drivers 
that implement logical device mapping. 

12.5.4 The saJoctl_cmd Member 

This member contains the I/O control command to be processed. This command 
usually maps directly to a SCSI I/O Command, but that is not necessary. For 
example, the Digital-specific SCSI_GET_SENSE command returns the sense data 
from the last failing command. A REQUEST SENSE command is not issued to the 
device, because autosense is assumed to have been enabled on the failing command, 
and the sense data is part of the common Peripheral Device Structure. 

12.5.5 The saJoctLscmd Member 

This member must be filled in for special commands implemented with a 
subcommand code. For example, magnetic tape I/O control commands have both an 
I/O control command code and a subroutine command code. 

12.5.6 The sa Joctl_data Member 

An I/O parameters buffer is required if the I/O control command transfers data to and 
from the kernel. If the request came from an application program, this buffer is 
normally passed into the driver ioctl routine. 

12.5.7 Thesa_device_name Member 

This member contains a pointer to the device name string that is used when reporting 
device errors. 

12.5.8 The sa_device_type Member 

This member contains the device type member from the Inquiry data. This member 
controls the SCSI/CAM Special Command Tables and the entries within each 
command table that are searched for the SCSI/CAM special I/O command being 
issued. 

12.5.9 The saJopJength and saJop_buffer Members 

These members are used internally by the SCSI/CAM special I/O interface when 
processing a command. If I/O would normally be performed directly to the I/O 
parameters buffer because no other buffer was set up, then a kernel buffer is allocated 
and set up in these members. 


12.5.10 The sa_file_flags Member 

This member contains the file flags passed into the device driver routines. The flags 
describe access control bits associated with the device. The file access flags are 
defined in the /usr/sys/h/f ile. h file. 
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12.5.11 


12.5.12 


12.5.13 


12.5.14 


12.5.15 


12.5.16 


12.5.17 


The sa.sensejength and sa.sense .buffer Members 

These members set up the sense buffer and expected sense data length that are used 
by autosense when device errors occur. If these members are not set up by the 
calling routine, then the SCSI/CAM special I/O interface uses the sense buffer 
allocated in the SCSI/CAM Peripheral Device Driver Working Set Structure that is 
pointed to by the SCSI I/O CCB. 

The sa.user.length and sa.user.buffer Members 

These members are set up by command setup routines to describe the user buffer and 
user data length required by a command. Requests from application programs that 
pass a user buffer and length in the I/O parameter buffers require a setup routine to 
copy this information into those members . The SCSI/CAM special I/O interface 
checks access and locking on this address range and sets up the address and length in 
the SCSI I/O CCB for the command. 

The sa_bp Member 

This member contains a pointer to a system I/O request buffer for commands that 
perform data movement directly to user address space. A system buffer is not 
required if a kernel data buffer is used for I/O. If the calling routine does not pass a 
previously allocated request buffer in this member, and the SCSI/CAM special I/O 
interface determines that the I/O requires one based on the I/O buffer address, then a 
request buffer is allocated and deallocated automatically by the SCSI/CAM special 
I/O interface. 

The sa_ccb Member 

This member contains a pointer to the SCSI I/O CCB for a command. If the calling 
routine does not specify a SCSI I/O CCB in this member, then the SCSI/CAM 
special I/O interface automatically allocates and deallocates a SCSI I/O CCB for the 
command. 


The special.cmd Member 

This member is used internally by the SCSI/CAM special I/O interface to save the 
SPECIAL_CMD after a command is located. 


The special .header Member 

This member can be used by the calling routine to specify the SCSI/CAM Special 
Command Table to search for the special command. This lets device drivers restrict 
the SCSI/CAM Special Command Tables that are searched. If this member is not 
used, then all the SCSI/CAM Special Command Tables in the list are searched for an 
entry that matches the special command being processed. 


The sa.cmd_parameter Member 

This member is used to store the command parameter, if any, from the command 
entry associated with this special command. This member is used by special support 
routines when setting up members for a particular CDB. 
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12.5.18 


12.5.19 


12.5.20 


12.5.21 


12.5.22 


12.5.23 


The sa_error Member 

This member contains the routine to be invoked when an error condition is detected. 
If not specified, a SCSI/CAM special I/O interface support routine handles the error 
condition. Otherwise, the routine is called as follows: 

status = (*sap->sa_error)(ccb, sense); 

This member can be specified for drivers requiring specialized error handling and for 
specific error logging. The SCSI/CAM special I/O interface’s error logging uses the 
mprintf facility to report errors. Both sense key and CAM status members are 
logged. 

The sa_start Member 

This member contains the routine that starts processing the SCSI I/O CCB. If not 
specified, the CAM xpt_action routine is used. The routine is invoked as 
follows: 

(void) ((sap->sa_start)(ccb); 


The sa_data Jength and sa_data_buffer Members 

These members are used internally by the SCSI/CAM special I/O interface to store 
the address and length of an additional kernel buffer required for a command. These 
members are usually initialized by the resulting value of the Special Command Entry 
Structure member, spc_data_length, but can be used by SCSI/CAM special I/O 
command developers if needed. 


The sa_cdb_pointer Member 

This member is used internally by the SCSI/CAM special I/O interface to save a 
pointer to the CDB for this special command. This member may point to a prototype 
CDB; to a driver-allocated CDB buffer, if the CAM_CDB_POINTER flag is set in 
CCB header; or to the CDB buffer allocated within the SCSI I/O CCB. This member 
is set up with the CDB buffer address before the Special Command Header Structure 
make CDB routine is invoked as follows: 

status = {*spc->spc_mkcdb)(sap, cdbp); 


The sa_cdbJength Member 

This member is used to specifiy the size in bytes of the CDB required by a SCSI 
command. If the Special Command Header Structure make CDB routine does not set 
up this member, then the SCSI Group Code is decoded to determine the length. 

The sa_cmd Jlags Member 

This member is initialized from the Special Command Header Structure 
spc_cmd_f lags member so SCSI/CAM special I/O command support routines 
have easy and quick access to the flags. 
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12.5.24 


12.5.25 


12.5.26 


12.5.27 


12.5.28 


12.5.29 


The sa_retry_count Member 

This member contains the number of retrys that were required to successfully 
complete the request. It is filled in by the SCSI/CAM special I/O interface after 
processing the command. 


The sa_retry_limit Member 

This member contains the maximum number of times a command is retried. The 
only retries automatically handled by the SCSI/CAM special I/O interface are a sense 
key of Unit Attention, or a SCSI bus status of Bus Busy or Reservation Conflict. All 
other error conditions must be handled by the calling routine. 


The sa_timeout Member 

This member contains the timeout value, in seconds, to use with the command being 
processed. This member can be specified by the calling routine. If it is not specified, 
the timeout value is taken from the Special Command Entry Structure. This member 
is used to initialize the cam_timeout member of the SCSI I/O CCB before issuing 
the command. 


The sa_xfer_resid Member 

This member contains the residual byte count of data movement commands. This 
member is copied from the cam_resid member of the SCSI I/O CCB before 
returning to the caller. 

The sa_specific Member 

This member is not set up or used by the SCSI/CAM special I/O interface. It 
provides a mechanism for device driver code to pass driver-dependant information to 
SCSI/CAM special I/O command support routines. The SCSI/CAM peripheral driver 
common routine ccmn_DoSpecialCmd passes the pointer to the Peripheral Device 
Structure in this member. 


Sample Function to Create a CDB 

The following sample function illustrates how to use the SCSI/CAM special I/O 
interface to create a CDB for a SCSI FORMATJJNIT command: 

/********************************************************************* 

* * 

* scmnMakeFormatUnit() - Make Format Unit Command Descriptor Block.* 

* * 

* Inputs: sap - Special command argument block pointer. * 

* cdbp - Pointer to command descriptor block. * 

* * 

* Return Value: * 

* Returns 0 for SUCCESS, or error code on failures. * 

* * 

**********************★**************★******★*******★★★★*******★*****/ 

int 

scmn_MakeFormatUnit (sap, cdbp) 
register struct special_args *sap; Qfl 
register struct dir format_cdb6 *cdbp; |2) 

{ 

register struct special_cmd *spc = sap->sa_spc; H 
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register struct format_params *fp; SI 

fp = (struct format_params *) sap->sa_iop_buffer; 
cdbp->opcode = (u_char) spc->spc_cmd_code; 
if (fp->fpdefects == VENDOR_DEFECTS) { S 
cdbp->fmt_data ■ 1; 
cdbp->cmp_list = 1; 

} else if (fp->fp_defects -- KNOWN_DEFECTS) { 
cdbp->fmt_data = 1; 
cdbp->cmp_list = 0; 

} else if (fp->fp_defects — NOJDEFECTS) { 
cdbp->fmt_data = 0; 
cdbp->cmp_list = 0; 

} 

cdbp->defect_list_fmt = fp->fp_format; |&j 
cdbp->vendor_specific = fp->fppattern; 
cdbp->interleave! = 0; 
cdbp->interleaveO = fp->fp_interleave; 
return (SUCCESS); 

} 

ED This line declares a register structure pointer to a Special I/O Argument Structure 
that controls processing of the I/O command. The Special I/O Argument 
Structure is defined in the /usr/sys/h/cam_special. h file. 

12 This line declares a register structure pointer to a structure containing the format 
for a 6-byte CDB. The structure is defined in the 
/usr/sys/h/scsi_direct. h file. 

SI This line declares a register structure pointer to a Special I/O Control Commands 
Structure that saves the SPECIAL_CMD after it is located in the sa_spc 
member of the Special I/O Argument Structure. The Special I/O Control 
Commands Structure is defined in the /usr/sys/h/cam_special .h file. 

SI This line declares a register structure pointer to a structure containing the format 
parameters for a SCSI FORMAT UNIT command. The structure is defined in the 
/usr/sys/h/rzdisk. h file. 

|§| This section tests the contents of the fp def ects member of the format 

parameters structure to determine the contents of the fmt_data and cmp_list 
members of the dir_format_cdb6 structure. 

12 This section assigns the contents of the dir_f ormat_cdb6 members to the 
equivalent members of the forma t_params structure. 


12.5.30 Sample Function to Set Up Parameters 

The following sample function illustrates how to use the SCSI/CAM special I/O 
interface to set up parameters for a SCSI FORMAT_UNIT command: 

/* *********************************************************************** 

★ * 

* scmn_SetupFormatUnit() - Set up Format Unit Parameters. * 

* * 

* Inputs: sap - Special command argument block pointer. * 

* data - The address of input/output arguments. * 

* * 

* Return Value: * 

* Returns 0 for SUCCESS, or error code on failures. * 

* * 

********************************************* * * ************************* f 

int 
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scmnSetupFormatUnit (sap, data) 
register struct special_args *sap; Q] 
caddr_t data; 

{ 

struct form2_defect_list_header defect_header; [ 2 ] 

register struct form2_defect_list_header *ddh = &defect_header; 

register struct format_params *fp; §1 

fp = (struct format_params *) data; 

sap->sa_user_buffer = (caddr_t) fp->fp_addr; 0 

/* 

* For diskettes, there are no defect lists. 

V 

if ( ((sap->sa_user_length *= fp->fp_length) == 0) && 

(fp->fpdefects == NO_DEFECTS) ) { 
sap->sa_cmd_flags &= ~(SPC_INOUT | SPC_DATA_INOUT); 
return (SUCCESS); 

} 


/* 

* Ensure the defect list address is valid (user address). 

*/ 

if ( ((sap->sa_flags & SA_SYSTEM_REQUEST) == 0) && 

1IS_KUSEG{fp->fp_addr) ) { 
return (EINVAL); 

} 

/* 

* The format parameters structure is not set up with the length 

* of the defect lists as it should be. Therefore, we must copy 

* in the defect list header then calculate the defect list length. 

*/ 

if (copyin ((caddr_t)fp->fp_addr, (caddr_t)ddh, sizeof(*ddh)) 1= 0) { 
return (EFAULT); 

} 

sap->sa_user_length = (int) ( (ddh->defect_lenl << 8) + 

ddh->defect_lenO + sizeof(*ddh) ); 

return (SUCCESS); 

} 

U This line declares a register structure pointer to a Special I/O Argument Structure 
that controls processing of the I/O command. The Special I/O Argument 
Structure is defined in the /usr/sys/h/cam_special. h file. 

[U This line declares a structure pointer to a structure containing the format defect 
list header for a SCSI FORMAT UNIT command. The structure is defined in the 
/usr/sys/h/rzdisk. h file. 

H This line declares a register structure pointer to a structure containing the format 
parameters for a SCSI FORMAT UNIT command. The structure is defined in the 
/usr/sys/h/rzdisk. h file. 

@ This line assigns the user buffer data address to the defect list address. 


12.6 SCSI/CAM Special I/O Control Command 

A SCSI/CAM special I/O control command has been defined to provide a single 
standard method of implementing new SCSI/CAM special I/O commands. A 
subcommand member is used to determine the specific SCSI command being issued. 
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The SCSI/CAM special I/O control command structure can be used both in porting 
applications using existing SCSI I/O control commands and in implementing new 
SCSI commands. Applications can be modified to use this structure to gain control 
over subsystem processing. For example, the SCSI/CAM special I/O command flags 
can be set to control error recovery and error reporting; sense data can be returned 
automatically by specifying a sense buffer address and length; and the command 
timeout and retry limit can be specified. 

A member in the Special I/O Control Commands Structure must be initialized to zero 
if a default value is desired. A nonzero member is used to override the default value. 

The SCSI I/O control command and its associated structure and definitions are 
included in the file /usr/sys/h/scsi_special. h. The scsi_special 
structure is defined as follows: 


/* 

* Structure for Processing Special I/O Control Commands. 


*/ 

struct scsi_special { 

u_long sp_flags; 
dev_t sp_dev; 
u_cha r s p_unit; 
u_char sp_bus; 
u_char sp_target; 
u_char sp_lun; 
int sp_sub_command; 

u_long sp_cmd_parameter; 
int sp__iop_length; 

caddr_t sp_iop_buffer; 
u_char sp_sense_length; 
u_char sp_sense_resid; 
caddr_t sp_sense_buffer; 
int sp_user_length; 

caddr_t sp_user_buffer; 
int sp_timeout; 

u_char sp_retry_count; 
u_char sp_retry_limit; 
int sp_xfer_resid; 


/* The special command flags */ 

/* Device major/minor number */ 

/* Device logical unit number */ 

/* SCSI host adapter bus number */ 
/* SCSI device target number */ 

/* SCSI logical unit number */ 

/* The subcommand */ 

/* Command parameter (if any) */ 

/* Parameters buffer length */ 

/* Parameters buffer address */ 

/* Sense data buffer length */ 

/* Sense data residual count */ 

/* Sense data buffer address */ 

/* User data buffer length */ 

/* User data buffer address */ 

/* Timeout for this command */ 

/* Retrys performed on command */ 
/* Times to retry this command */ 
/* Transfer residual count */ 


This structure is used with the following SCSI Special I/O Control Command: 

#define SCSI_SPECIAL _IOWR('p', 100, struct scsi_special) 


12.6.1 The sp_flags Member 

This member controls the actions of the SCSI/CAM special I/O interface. The low 
order three bits can be set by the calling routine. The other bits are reserved for use 
by SCSI/CAM peripheral drivers and the SCSI/CAM special I/O interface routines. 
The bits that can be set by the calling routine are described as follows: 


Flag Name 


Description 

SA_NO_E R RO R _ 

RECOVERY 

Do not perform error recovery. 

SA_N0_E RR 0 R _ 

LOGGING 

Do not log error messages. 

SA_NO_S L EE p _ 

INTR 

Do not allow sleep interrupts. 
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12.6.2 The sp_dev, sp_unit, sp_bus, sp_target, and sp_lun Members 

These members pass the device major/minor number pair and the device bus, target, 
LUN, and unit information to the SCSI/CAM special I/O interface when the I/O 
control command is not being issued to a SCSI/CAM peripheral device driver. These 
members provide the necessary hooks to allow software pseudodevice drivers, such 
as the User Agent driver, to send requests to the SCSI/CAM special I/O interface. 

12.6.3 The sp_sub_command Member 

This member contains the SCSI/CAM special I/O subcommand code of the SCSI 
command to execute. This member can also be defined as an I/O control command 
to support backwards compatibility with preexisting SCSI I/O control commands. 

The SCSI/CAM special I/O interface detects an I/O control command, as opposed to 
a subcommand code, and coerces the arguments into the appropriate format for 
processing by the support routines associated with that I/O control command. The 
predefined subcommand codes are listed in the file 
/usr/sys/h/scsi_special.h. 

12.6.4 The sp_cmd_parameter Member 

This member contains the command parameter, if any, for the SCSI special I/O 
command being issued. This parameter is specific to the special command 
processing routines and is not used directly by the SCSI/CAM special I/O interface 
routines. 

12.6.5 The spjopjength and spJop_buffer Members 

These members contain the I/O parameters buffer and length for those commands that 
require additional parameters. These members are used by the special command 
processing routines to obtain and set up additional information prior to issuing the 
SCSI command. For example, the SCSI FORMAT_UNIT I/O control command 
passes a format_params structure that describes the format, length, pattern, and 
interleave information for the defect list. This information is used by the 
scmn_MakeFormatUnit support routine when creating the CDB for this 
command. 

12.6.6 The sp_sense_length, sp_sense_resid, and sp_sense_buffer 
Members 

These members contain the buffer, length, and residual byte count for the sense data 
that is returned when device errors occur. If these members are specified, then the 
last sense data is saved in the Peripheral Device Structure from which it can be 
obtained by the Digital-specific SCSI_GET_SENSE I/O control command. 

12.6.7 The sp_userjength and sp_user_buffer Members 

These members contain the user buffer and length for those commands that require 
them. The SCSI/CAM special I/O interface performs verification, locking, and 
unlocking of the user pages when processing the command. 
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12.6.8 The sp.timeout Member 

This member can be specified to override the default timeout, in seconds, which is 
usually taken from the Special Command Entry Structure. 

12.6.9 The sp_retry_count Member 

This member contains the number of retrys that were required to successfully 
complete the request. It is filled in by the SCSI/CAM special I/O interface after 
processing the command. 

12.6.10 The sp_retryjimit Member 

This member contains the maximum number of times a command is retried. The 
only retries automatically handled by the SCSI/CAM special I/O interface are a sense 
key of Unit Attention, or a SCSI bus status of Bus Busy or Reservation Conflict. All 
other error conditions must be handled by the calling routine. 


12.6.11 The sp_xfer_resid Member 

This member is filled in with the transfer residual byte count when a command 
completes. The SCSI/CAM special I/O interface copies the cam_resid member of 
the SCSI I/O CCB to this member before completing the request. 

12.6.12 Sample Function to Create an I/O Control Command 

The following sample function illustrates how to use the SCSI/CAM special I/O 
interface to create an I/O control command: 

/********************************************************************** 
* 

* DoIoctl() Do An I/O Control Command. 

* 

* Description: 

* This routine issues the specified I/O control command to the 

* 

* file descriptor associated with the CD-ROM device driver. 

* 

* Inputs: cmd = The I/O control command. 

* argp - The command argument to pass. 

* msgp = The message to display on errors. 

* 

* Return Value: 

* Returns 0 / -1 = SUCCESS / FAILURE. 

* 

********************************************************************** 

int 

Doloctl (cmd, argp, msgp) 
int cmd; 
caddr_t argp; 
caddr_t msgp; 

{ 

int status; 

#if defined(CAM) 

struct scsispecial specialcmd; OD 

register struct scsi_special *sp = &special_cmd; 

register struct extended_sense *es; [H 

es = (struct extended_sense *)SenseBufPtr; 
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bzero ((char *) sp, sizeof(*sp)); 
bzero ((char *) es, sizeof(*es)); 
sp->sp_sub_command = cmd; §1 
sp->sp_sense_length = sizeof(*es); 
sp->sp_sense_buffer = (caddr_t) es; 

sp->sp_iop_length = ((cmd & ~ (_IOC__INOUT |_IOC_VOID)) >> 16); 
sp->sp_iop_buffer = argp; 

if ((status = ioctl (CdrFd, SCSIJSPECIAL, sp)) < 0) { ® 
perror (msgp); 
if (es->snskey) { 

cdbg_DumpSenseData (es); 

} 

} 

#else /* !defined(CAM) */ 

if ((status = ioctl (CdrFd, cmd, argp)) < 0) { 
perror (msgp); 

} 

#endif /* defined(CAM) */ 
return (status); 

} 

0 This line declares a structure to process a special I/O control command. The 
scsi_special structure is defined in the /usr/sys/h/scsi__special .h 
file. 

El This line declares a structure defining the extended sense format for a REQUEST 
SENSE command. The extended_sense structure is defined in the 
/usr/sys/h/rzdisk. h file. 

El This section assigns the program parameters to the special_cmd members. 

H This is a standard I/O control call issued from application code. The 

SCSI_SPECIAL argument is defined in the /usr/sys/h/scsi_special. h 
file. 


12.7 Other Sample Code 

This section contains other driver code samples that use the SCSI/CAM special I/O 
interface. 


12.7.1 


Sample Code to Open a Device 


The following sample code illustrates how to use the SCSI/CAM special I/O 
interface to open a CDROM device from a device driver: 




* 


* 


* cdrom_open() - Driver Entry Point to Open CD-ROM Device. 

* 

* Inputs: dev - The device major/minor number pair. 

* flags - The file open flags (read/write/nodelay). 

* 


Hr 

Hr 

Hr 

Hr 

Hr 


* Outputs: Returns 0 for Success or error code on Failure. * 

* * 


************************************************************************/ 

cdromopen (dev, flags) 
dev_t dev; 
int flags; 

{ 

register PDRV_DEVICE *pd; ffl 
DIR_READ_CAP_DATA read_capacity; @ 
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DIR_READ_CAP_DATA ‘capacity *= &read_capacity; 


pd - GET_PDRV_PTR (dev); g) 

status = cdrom_read_capacity (pd, capacity, flags); 


return (status); 

} 

/************************************************************************ 

* * 

* cdrom_read_capacity() - Obtain Disk Capacity Information. * 

* * 

* Inputs: pd = Pointer to peripheral driver structure. * 

* capacity = Pointer to read capacity data buffer. * 

* flags = The file open flags. * 

* * 

* Outputs: Returns 0 for Success or error code on Failure. * 

* * 
♦a**********************************************************************/ 

int 

cdrom_read_capacity (pd, capacity, flags) 

PDRV_DEVICE *pd; 

DIR_READ_CAP_DATA ‘capacity; 
int flags; 

{ 

int status; 

PRINTD(DEV_BUS_ID(pd->pd_dev), DEV_TARGET(pd-> pd_dev), 

DEV_LUN(pd-> pd_dev), CAMD_CDROM, 0 
("[%d/%d/%d] cdrom_read_capacity: ENTRY - pd - Ox%x, \ 
capacity - Ox%x, flags = Ox%xO, 

DEV_BUS_ID(pd-> pd_dev), DEV_TARGET(pd->pd_dev), 

DEV_LUN(pd->pd_dev), pd, capacity, flags)); 

bzero ((char *)capacity, sizeof(‘capacity)); 

status = ccmn_SysSpecialCmd (pd->pd_dev, SCSI_READ_CAPACITY, (gj 
(caddr_t) capacity, flags, (CCB_SCSIIO *) 0, SA_NO_ERROR_LOGGING); 

PRINTD(DEV_BUS_ID(pd->pd_dev), DEV_TARGET(pd->pd_dev), 

DEV_LUN(pd-> pd_dev), CAMD_CDROM, 

("[%d/%d/%d] cdrom_read_capacity: EXIT - status = %d (%s)0, 
DEV_BCJS_ID(pd->pd_dev), DEV_TARGET (pd - > pd_dev), 

DEV_LUN(pd->pd_dev), status, cdbgSystemStatus(status))); 0 

return (status); 

} 

U This line assigns a register to a Peripheral Device Structure pointer for the device 
to be opened. The Peripheral Device Structure is defined in the 
/usr/sys/h/pdrv. h file. 

0 This line declares a structure to contain the capacity data returned for the device. 
The DIR_READ_CAP_DATA structure is defined in the 
/usr/sys/h/scsi_direct. h file. 

0 This line calls the GET_PDRV_PTR macro to return a pointer to the Peripheral 
Device Structure for the device. The GET_PDRV_PTR macro is defined in the 
/usr/sys/h/pdrv. h file. 
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151 This section uses the bus, target, and lun information to be printed if the 
CAMD_CDROM flag is set. The CAMD_CDROM flag is defined in the 
/usr/sys/io/cam/cam_debug. h file. 

H) This section calls the SCSI/CAM peripheral common routine 

ccmn_SysSpecialCmd, to issue the SCSI I/O command, passing the 
major/minor device number pair for the device and the SCSI_READ_CAPACITY 
ioctl command, which is defined in the /usr/sys/h/rzdisk. h file. It 
sets the SA_NO_ERROR_LOGGING flag, which is defined in the 
/usr/sys/h/cam_special. h file for device drivers, and in the 
/usr/sys/h/scsi_special. h file for application programs. 

@ This debug line calls the cdbg SystemStatus routine, passing the status as 
an argument. 


12.7.2 Sample Code to Create a Driver Entry Point 

The following sample code illustrates how to use the SCSI/CAM special I/O 
interface to create a driver entry point for I/O control commands: 

/********************************************************************* 


* * 

* cdrom_ioctl() - Driver Entry Point for I/O Control Commands. * 

* * 

* Inputs: dev = The device major/minor number pair. * 

* cmd = The I/O control command code. * 

* data = The I/O parameters data buffer. * 

* flags = The file open flags (read/write/nodelay). * 

* * 

* Outputs: Returns 0 for Success or error code on Failure. * 

* * 


*********************************************************************/ 

int 

cdrom_ioctl (dev, cmd, data, flags) 

dev_t dev; 

register int cmd; 

caddr_t data; 

int flags; 

{ 

register PDRV_DEVICE *pd; E 
register DISK_SPECIFIC *cdisk; 
register DEV_DESC *dd; 
int status; 

pd = GET_PDRV_PTR(dev) ; HI 
dd = pd->pd_dev_desc; 

cdisk = (DISK_SPECIFIC *)pd->pd_specific; 
switch (cmd) { 


/* Process Expected I/O Control Commands */ 


} 


default: 

/* 

* Process Special I/O Control Commands. 

*/ 

status = ccmn_DoSpecialCmd (dev, cmd, data, flags, 
(CCB_SCSI10 *) 0, 0); 

break; 


1 
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} 


return (status); 


GO This section reserves registers for pointers to a Peripheral Device Structure and a 
Device Descriptor Structure, both of which are defined in the 
/usr/sys/h/pdrv. h file, and to a DISK_SPECEFIC structure, which is 
defined in the /usr/sys/io/cam/cam_disk. h file. 

12 This line calls the GET_PDRV_PTR macro to return a pointer to the Peripheral 
Device Structure for the device. The GETJPDRV_PTR macro is defined in the 
/usr/sys/h/pdrv.h 

ID This section calls the SCSI/CAM peripheral common routine, 
ccmn_DoSpecialCmd, to issue the special I/O command. 
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Header Files Used by Device Drivers 


This appendix contains the following: 

• A list of header files used by all device drivers 

• A list of header files used by SCSI/CAM peripheral device drivers 

• The contents of the /usr/sys/h/cam. h file. 

Table A-l lists the header files used by all SCSI device drivers, with a short 
description of the contents of each. For convenience, the full path name for the file 
is given and the files are listed in alphabetical order. However, device driver code 
should be written to include header files by specifying the relative path name instead 
of the hill path name. For example, /usr/sys/h/buf. h, is the full path name 
for the file buf. h , but device driver code to include buf . h should be written as 
follows: 

#include . ./h/buf.h 


Table A-1: Header Files Used by Device Drivers 


Header File Contents 


/usr/sys/h/buf.h 

/usr/sys/h/clist.h 
/usr/sys/h/conf.h 


/usr/sys/h/devio.h 
/usr/sys/h/dir.h 
/usr/sys/h/errno.h 

/usr/sys/h/file.h 


Defines the buf structure used to pass I/O 
requests to the strategy routine of a 
block driver. 

Defines the cblock structure used to hold 
clist data. 

Defines the bdevsw (block device 
switch), cdevsw (character device 
switch), and linesw (tty control line 
switch) structures. This file is included in 
the source file 

/us r/sys/machine/common/conf. c. 

Defines common structures and definitions 
for device drivers and ioctl. 

Defines structures and macros that operate 
on directories. 

Defines the error codes returned to a user 
process by a driver. The codes EIO, 
ENXIO, EACCES, EBUSY, ENODEV, and 
einval are used by driver routines. 

Defines I/O mode flags supplied by user 
programs to open and f cntl system 
calls. 




Table A-1: (continued) 


Header File 

/usr/sys/h/inode.h 

/usr/sys/h/ioctl.h 

/usr/sys/h/kernel.h 
/usr/sys/h/map.h 

/usr/sys/h/mbuf.h 

/usr/sys/h/mtio.h 
/usr/sys/h/param. h 
/usr/sys/h/proc.h 

/usr/sys/h/rzdisk.h 
/usr/sys/h/scsi_all.h 

/usr/sys/h/scsi_cdbs.h 
/usr/sys/h/scsi_direct.h 

/usr/sys/h/scsi_opcodes.h 
/usr/sys/h/scsi_phases.h 
/usr/sys/h/scsi_rodirect.h 

/usr/sys/h/scsi_sequential 

/usr/sys/h/smp_lock.h 
/usr/sys/h/systm.h 

/usr/sys/h/time.h 

A-2 Header Files Used by Device Drivers 


Contents 


Defines values associated with the generic 
file system. 

Defines commands for ioctl routines in 
different drivers. 

Defines global variables used by the kernel. 

Defines structures associated with resource 
allocation maps. 

Defines constants related to memory 
allocation and macros used for type 
conversion. 

Defines commands and structures for 
magnetic tape operations. 

Defines constants and macros used by the 
ULTRIX kernel. 

Defines the proc structure, which defines 
a user process. This file is not usually 
included by device driver source files. 

Definitions and data structures for SCSI 
disks. 

Definitions and data structures that apply to 
all SCSI device types according to Chapter 
7 of the SCSI-2 specification. 

Definitions and data structures that apply to 
Command Descriptor Blocks. 

Definitions and data structures that apply to 
all SCSI direct-access devices according to 
Chapter 8 of the SCSI-2 specification. 

Definitions of operation codes according to 
Chapter 6 of the SCSI-2 specification. 

Definitions of SCSI bus phases according to 
Chapter 5 of the SCSI-2 specification. 

Definitions and data structures that apply to 
read-only direct-access devices according to 
Chapter 13 of the SCSI 2 specification. 

Definitions and data structures that apply to all 
SCSI sequential-access devices according to 
Chapter 9 of the SCSI-2 specification. 

Defines variables and structures for managing 
locks for symmetric multiprocessing. 

Defines global variables, such as the number of 
entries in the block switch and the number of 
character switch entries. It also defines the 
structure of the system-entry table. 

Defines structures and symbolic names used by 
time-related routines and macros. 





Contents 


Table A-1: (continued) 


Header File 


/usr/sys/h/tty.h 

Defines parameters and structures associated 
with interactive terminals; also defines the 
clist structure. This file can be included by 
any device driver that uses the clist 
structure. 

/usr/sys/h/types.h 

Defines system data types and major and minor 
device macros. 

/usr/sys/h/uio.h 

Definition of the uio structure, some symbolic 
names, and an enumerated data type that can be 
assigned the value uiO_READ or 

UIO_WRITE. 

/usr/sys/h/user.h 

Defines the user structure that describes a 
user process and passes information about I/O 
requests to device drivers. 

/usr/sys/h/vm.h 

Contains a sequence of include statements that 
includes all of the virtual memory-related files. 
Including this file is a quick way of including 
all of the virtual memory-related files. 

/usr/sys/h/vmmac.h 

Definitions for the vtokpf num kernel routine. 

/usr/sys/machine/common/cpuconf.h 

Defines a variety of macros, constants, and 
structures used by the system. 


Table A-2 lists the header files used by SCSI/CAM peripheral device drivers, along 
with a short description of the contents of each. For convenience, the full path name 
for the file is given and the files are listed in alphabetical order. 

Table A-2: Header Files Used by SCSI/CAM Drivers 


Header File 

Contents 

/usr/sys/h/cam.h 

Definitions and data structures for the CAM 
subsystem interface. 

/usr/sys/h/cam_generic.h 

Examples of definitions and data structures 
for a CAM generic device driver. 

/usr/sys/h/cam_logger.h 

Definitions and data structures for CAM 
subsystem error logging. 

/usr/sys/h/cam_special.h 

Definitions for the SCSI/CAM special I/O 
interface. 

/usr/sys/h/dec_cam.h 

Digital-spcific definitions and data 
structures for the CAM routines. 

/usr/sys/h/pdrv.h 

Definitions and data structures for the 

SCSI/CAM common routines. 

/usr/sys/h/scsi_special.h 

Definitions and data structures for the 

SCSI/CAM special I/O control interface. 


Header Files Used by Device Drivers A-3 







Table A-2: (continued) 

Header File Contents 

/usr/sys/h/uagt. h Definitions and data structures for the User 

Agent Device Driver (UAGT) that controls 
access to the CAM subsystem. 

/usr/sys/h/xpt. h Definitions and data structures for the 

Transport Layer, XPT, in the CAM 
subsystem. 

/usr/sys/io/ccum/cam_conf ig. h SCSI/CAM peripheral device driver 

configuration definitions. 

/usr/sys/io/cam/cam_debug. h CAM debugging macros. 

/usr/sys/io/cam/cam disk. h Definitions and data structures for 

SCSI/CAM disk devices. 

/usr/sys/io/cam/cam_errlog. h CAM error logging macros. 

/usr/sys/io/cam/cam_tape. h Definitions and data structures for 

SCSI/CAM tape devices. 

/usr/sys/io/cam/ccf g. h Definitions and data structures for the 

Configuration driver module in the CAM 
subsystem. 

/usr/sys/io/cam/dme. h Definitions and data structures needed by 

the CAM SIM Data Mover Engine (DME). 

/usr/sys/io/cam/dme_3min_94_dma. h 

Definitions and data structures needed by the 
CAM SIM Data Mover Engine (DME) for the 
DECstation 5000, Model 100 series. 

/usr/sys/io/cam/dme_pmax_s i i_r am. h 

Definitions and data structures needed by the 
CAM SIM Data Mover Engine (DME) for the 
DECstation 2100 and DECstation 3100. 

/usr/sys/io/cam/dme_turbo_94_ram.h 

Definitions and data structures needed by the 
CAM SIM Data Mover Engine (DME) for the 
DECstation 5000, Model 200 series. 

/usr/sys/io/cam/sim. h Definitions and data structures needed by the 

CAM SIM-related files. 

/usr/sys/io/cam/sim94 . h Definitions and data structures needed by the 

NCR53C94 SIM module. 

/usr/sys/io/cam/simcirq. h Definitions and data structures needed by the 

circular-queue-related functions contained in the 
Digital CAM subsystem. 

/usr/sys/io/cam/sim_coinmon. h Definitions common to all the SIM-related 

source files. 

/usr/sys/io/cam/sim_conf ig. h CAM SIM subsystem configuration definitions. 

/usr/sys/io/cam/sim_sii. h Definitions and data structures needed by the 

Digital SII SIM module. 

/usr/sys/io/cam/sim_target. h Definitions needed for target-mode operation of 

the SIM. 
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Table A-2: (continued) 


Header File 

Contents 

/usr/sys/io/cam/sim_xpt.h 

Macros and definitions that are specific to the 
SIM XPT component of the USCA subsystem. 


The contents of /usr/sys/h/cam. h follow: 

/* cam.h Version 1.09 Jul. 18, 1991 */ 

/* This file contains the definitions and data structures for the CAM 
Subsystem interface. The contents of this file should match what 
data structures and constants that are specified in the CAM document, 
X3T9.2/90-186 Rev 2.5 that is produced by the SCSI-2 committee. 


/* 


V 


/* Defines for the XPT function codes, Table 8-2 in the CAM spec. */ 


/* Common function commands, 0x00 - OxOF */ 


#define XPT_NOOP 0x00 
#define XPT_SCSI_IO 
#define XPT_GDEV_TYPE 
#define XPT_PATH_INQ 
^define XPT_REL_SIMQ 
#define XPT_SASYNC_CB 
^define XPT SDEV TYPE 


/* Execute Nothing */ 

0x01 /* Execute the requested SCSI IO */ 

0x02 /* Get the device type information */ 

0x03 /* Path Inquiry */ 

0x04 /* Release the SIM queue that is frozen */ 

0x05 /* Set Async callback parameters */ 

0x06 /* Set the device type information */ 


/* XPT SCSI control functions, 0x10 - OxlF */ 

#define XPT_ABORT0x10 /* Abort the selected CCB */ 

#define XPT_RESET_BUS 0x11 /* Reset the SCSI bus */ 

#define XPT_RESET_DEV 0x12 /* Reset the SCSI device, BDR */ 

^define XPT_TERM_IO 0x13 /* Terminate the I/O process */ 

/* HBA engine commands, 0x20 - 0x2F */ 

#define XPT_ENG_INQ 0x20 /* HBA engine inquiry */ 

Jfdefine XPT_ENG_EXEC 0x21 /* HBA execute engine request */ 


/* Target mode commands, 0x30 - 0x3F */ 

^define XPT_EN_LUN 0x30 /* Enable LUN, Target mode support */ 

#define XPT_TARGET_IO 0x31 /* Execute the target IO request */ 


#define XPT_FUNC 0x7F /* TEMPLATE */ 

#define XPT_VUNIQUE 0x80 /* All the rest are vendor unique commands */ 


/* . V 

/* General allocation length defines for the CCB structures. */ 

^define IOCDBLEN 12 
Hdefine VUHBA 
^define SIM_ID 
#define HBA_ID 
^define SIM_PRIV50 

/* Structure definitions for the CAM control blocks, CCB's for the 
subsystem. */ 


/* Space for the CDB bytes/pointer */ 

14 /* Vendor Unique HBA length */ 

16 /* ASCII string len for SIM ID */ 
16 /* ASCII string len for HBA ID */ 
/* Length of SIM private data area */ 


/* Common CCB header definition. */ 
typedef struct ccb_header 
t 

struct ccb_header *my_addr; /* The address of this CCB */ 
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u_short cam_ccb_len; /* Length of the entire CCB */ 

u_char cam_func_code; /* XPT function code */ 

u_char cam_status; /* Returned CAM subsystem status */ 

u_char cam_hrsvdO; /* Reserved field, for alignment */ 

u_char cam_path_id; /* Path ID for the request */ 

u_char cam_target_id; /* Target device ID */ 
u_char cam_target_lun; /* Target LUN number */ 
u_long cam_flags; /* Flags for operation of the subsystem */ 

} CCB_HEADER; 

/* Common SCSI functions. */ 

/* Union definition for the CDB space in the SCSI I/O request CCB */ 
typedef union cdb_un 
t 

uchar *cam_cdb_ptr; /* Pointer to the CDB bytes to send */ 

u_char cam_cdb_bytes[ IOCDBLEN ]; /* Area for the CDB to send */ 

} CDB_UN; 

/* Get device type CCB */ 
typedef struct ccb_getdev 
{ 

CCB_HEADER cam_ch; 
char *cam_inq_data; 
u_char cam_pd_type; 

} CCB_GETDEV; 

/* Path inquiry CCB */ 
typedef struct ccb_pathinq 
t 

CCB_HEADER cam_ch; /* Header information fields */ 

u_char cam_version_num; /* Version number for the SIM/HBA */ 
u_char cam_hba_inquiry; /* Mimic of INQ byte 7 for the HBA */ 
u_char cam_target_sprt; /* Flags for target mode support */ 
u_char cam_hba_misc; /* Misc HBA feature flags */ 
u_short cam_hba_eng_cnt; /* HBA engine count */ 

u_char cam_vuhba_flags[ VUHBA ]; /* Vendor unique capabilities */ 
u_long cam_sim_priv; /* Size of SIM private data area */ 
u_long cam_async_flags; /* Event cap. for Async Callback */ 
u_char cam_hpath_id; /* Highest path ID in the subsystem */ 
u_char cam_initiator_id; /* ID of the HBA on the SCSI bus */ 
u_char cam_prsvdO; /* Reserved field, for alignment */ 

u_char cam_prsvdl; /* Reserved field, for alignment */ 

char cam_sim_vid[ SIM_ID ]; /* Vendor ID of the SIM */ 

char cam_hba_vid[ HBA_ID ]; /* Vendor ID of the HBA */ 

u_char *cam_osd_usage; /* Ptr for the OSD specific area */ 

} CCB_PATHINQ; 

/* Release SIM Queue CCB */ 
typedef struct ccb_relsim 
{ 

CCBHEADER cam_ch; /* Header information fields */ 

} CCBRELSIM; 

/* SCSI I/O Request CCB */ 
typedef struct ccbscsiio 

t 

CCB_HEADER cam_ch; /* Header information fields */ 

u_char *cam_pdrv_ptr; /* Ptr used by the Peripheral driver */ 
CCB_HEADER *cam_next_ccb; /* Ptr to the next CCB for action */ 

u_char *cam_req_map; /* Ptr for mapping info on the Req. */ 
void (*cam_cbfcnp){); /* Callback on completion function */ 

u_char *cam_data_ptr; /* Pointer to the data buf/SG list */ 

ulong cam_dxfer_len; /* Data xfer length */ 

u_char *cam_sense_ptr; /* Pointer to the sense data buffer */ 


/* Header information fields */ 

/* Ptr to the inquiry data space */ 

/* Periph device type from the TLUN */ 
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u_char cam_sense_len; /* Num of bytes in the Autosense buf */ 
u_char cam_cdb_len; /* Number of bytes for the CDB */ 

u_short cam_sglist_cnt; /* Num of scatter gather list entries */ 
u_long cam_osd_rsvdO; /* OSD Reserved field, for alignment */ 

u_char cam_scsi_status; /* Returned scsi device status */ 

u_char cam_sense_resid; /* Autosense resid length: 2's comp */ 
u_char cam_osd_rsvdl[2]; /* OSD Reserved field, for alignment */ 
long cam_resid; /* Transfer residual length: 2's comp */ 

CDB_UN cam_cdb_io; /* Union for CDB bytes/pointer */ 

u_long cam_timeout; /* Timeout value */ 

u_char *cam msgptr; /* Pointer to the message buffer */ 
u_short cam msgb len; /* Num of bytes in the message buf */ 

u_jshort cam_vu_flags; /* Vendor unique flags */ 

u_char cam_tag_action; /* What to do for tag queuing */ 

u_char camiorsvdO[3]; /* Reserved field, for alignment */ 

uchar camsimpriv[ SIMPRIV ]; /* SIM private data area */ 

} CCB_SCSIIO; 

/* Set Async Callback CCB */ 
typedef struct ccb_setasync 
{ 

CCB_HEADER cam_ch; /* Header information fields */ 

u_long cam_async_flags; /* Event enables for Callback resp */ 
void (*cam_async_func)(); /* Async Callback function address */ 

u_char *pdrv_buf; /* Buffer set aside by the Per. drv */ 

u_char pdrv_buf_len; /* The size of the buffer */ 

} CCB_SETASYNC; 

/* Set device type CCB */ 
typedef struct ccb_setdev 
t 

CCB_HEADER cam_ch; /* Header information fields */ 

u_char cam_dev_type; /* Val for the dev type field in EDT */ 

} CCB_SETDEV; 

/* SCSI Control Functions. */ 

/* Abort XPT Request CCB */ 
typedef struct ccb_abort 
{ 

CCB_HEADER cam_ch; /* Header information fields */ 

CCB_HEADER *cam_abort_ch; /* Pointer to the CCB to abort */ 

} CCB_ABORT; 

/* Reset SCSI Bus CCB */ 
typedef struct ccb_resetbus 
t 

CCB_HEADER cam_ch; /* Header information fields */ 

} CCBRESETBUS; 

/* Reset SCSI Device CCB */ 
typedef struct ccbresetdev 

{ 

CCBHEADER cam_ch; /* Header information fields */ 

} CCB_RESETDEV; 

/* Terminate I/O Process Request CCB */ 
typedef struct ccb_termio 
t 

CCB_HEADER cam_ch; /* Header information fields */ 

CCB_HEADER *cam_termio_ch; /* Pointer to the CCB to terminate */ 
} CCB_TERMIO; 

/* Target mode structures. */ 
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typedef struct ccbenlun 

{ 

CCB_HEADER cam_ch; /* Header information fields */ 

u_short cam_grp6_len; /* Group 6 VU CDB length */ 

u_short cam_grp7 len; /* Group 7 VU CDB length */ 

u_char *cam_ccb_listptr; /* Pointer to the target CCB list */ 
u_short camccblistcnt; /* Count of Target CCBs in the list */ 

} CCB_EN_LUN; 

/* HBA engine structures. */ 
typedef struct ccb_eng_inq 

t 

CCB_HEADER cam_ch; /* Header information fields */ 

u short cam_eng_num; /* The number for this inquiry */ 

u char camengtype; /* Returned engine type */ 

u_char cam_eng_algo; /* Returned algorithm type */ 

u_long cam_eng_memory; /* Returned engine memory size */ 

} CCB_ENG_INQ; 

typedef struct ccb_eng_exec /* NOTE: must match SCSIIO size */ 

{ 

CCB_HEADER cam_ch; /* Header information fields */ 

u_char *cam_pdrv_ptr; /* Ptr used by the Peripheral driver */ 
u_long cam_engrsvdO; /* Reserved field, for alignment */ 

u_char *cam_req_map; /* Ptr for mapping info on the Req. */ 

void (*cam_cbfcnp)(); /* Callback on completion function */ 

u_char *cam_data_ptr; /* Pointer to the data buf/SG list */ 
u_long cam_dxfer_len; /* Data xfer length */ 

u_char *cam_engdata_ptr; /* Pointer to the engine buffer data */ 
u_char cam_engrsvdl; /* Reserved field, for alignment */ 

u_char cam_engrsvd2; /* Reserved field, for alignment */ 

u_short cam_sglist_cnt; /* Num of scatter gather list entries */ 
u_long cam_dmax_len; /* Destination data maximum length */ 

u_long cam_dest_len; /* Destination data length */ 

long cam_src_resid; /* Source residual length: 2's comp */ 

u_char cam_engrsvd3[12]; /* Reserved field, for alignment */ 
u_long cam_timeout; /* Timeout value */ 

u_long cam_engrsvd4; /* Reserved field, for alignment */ 

u_short cam_eng_num; /* Engine number for this request */ 

u_short cam_vu_flags; /* Vendor unique flags */ 

u_char cam_engrsvd5; /* Reserved field, for alignment */ 

u_char cam_engrsvd6[3]; /* Reserved field, for alignment */ 

u_char cam_sim_priv[ SIM_PRIV ]; /* SIM private data area */ 

} CCB_ENG_EXEC; 

/* The CAM_SIM_ENTRY definition is used to define the entry points for 
the SIMs contained in the SCSI CAM subsystem. Each SIM file will 
contain a declaration for it's entry. The address for this entry will 
be stored in the cam_conftbl[] array along will all the other SIM 
entries. */ 

typedef struct cam_sim_entry 

t 

long (*sim_init) (); /* Pointer to the SIM init routine */ 

long (*sim_action) (); /* Pointer to the SIM CCB go routine */ 

} CAM_SIM_ENTRY; 

/* .-.. V 

/* Defines for the CAM status field in the CCB header. */ 

^define CAM_REQ_INPROG 0x00 /* CCB request is in progress */ 

^define CAM_REQ_CMP 0x01 /* CCB request completed w/out error */ 

^define CAM_REQ_ABORTED 0x02 /* CCB request aborted by the host */ 
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((define CAM_UA_ABORT 0x03 /* Unable to Abort CCB request */ 

((define CAM_REQ_CMP_ERR 0x04 /* CCB request completed with an err */ 

((define CAM_BUSY 0x05 /* CAM subsystem is busy */ 

((define CAM_REQ_INVALID 0x06 /* CCB request is invalid */ 

((define CAM_PATH_INVALID0x07 /* Path ID supplied is invalid */ 

((define CAM_DEV_NOT_THERE0x08 /* SCSI device not installed/there */ 

((define CAM_UA_TERMIO 0x09 /* Unable to Terminate I/O CCB req */ 

((define CAM_SEL_TIMEOUT OxOA /* Target selection timeout */ 

((define CAM_CMD_TIMEOUT OxOB /* Command timeout */ 

#define CAM_MSG_REJECT_REC0x0D /* Message reject received */ 

((define CAM_SCSI_BUS_RESET0x0E /* SCSI bus reset sent/received */ 

((define CAM_UNCOR_PARITY0x0F /* Uncorrectable parity err occurred */ 

((define CAM_AUTOSENSE_FAIL0xl0 /* Autosense: Request sense cmd fail */ 

#define CAM_NO_HBA 0x11 /* No HBA detected Error */ 

(f define CAM_DATA_RUN_ERR0xl2 /* Data overrun/underrun error */ 
ffdef ine CAM_UNEXP_BUSFREE0xl3 /* Unexpected BUS free */ 

((define CAM_SEQUENCE_FAIL0xl4 /* Target bus phase sequence failure */ 

#define CAM_CCB_LEN_ERR 0x15 /* CCB length supplied is inadequate */ 

((define CAM_PROVIDE_FAIL0xl6 /* Unable to provide requ. capability */ 

((define CAM_BDR_SENT 0x17 /* A SCSI BDR msg was sent to target */ 

((define CAM_REQ_TERMIO 0x18 /* CCB request terminated by the host */ 

#define CAM_LUN_INVALID 0x38 /* LUN supplied is invalid */ 

Sdefine CAM_TID_INVALID 0x39 /* Target ID supplied is invalid */ 

jfdefine CAM_FUNC_NOTAVAIL0x3A /* The requ. func is not available */ 

jldefine CAM_NO_NEXUS 0x3B /* Nexus is not established */ 

^define CAM_IID_INVALID 0x3C /* The initiator ID is invalid */ 

#define CAM_CDB_RECVD 0x3E /* The SCSI CDB has been received */ 

#define CAM_SCSI_BUSY 0x3F /* SCSI bus busy */ 

#define CAM_SIM_QFRZN 0x40 /* The SIM queue is frozen w/this err */ 

#define CAM_AUTOSNS_VALID0x80 /* Autosense data valid for target */ 

#define CAM_STATUS_MASK 0x3F /* Mask bits for just the status # */ 

/* ..-.V 

/* Defines for the CAM flags field in the CCB header. */ 

#define CAM_DIR_RESV 0x00000000 /* Data direction (00: reserved) */ 

^define CAM_DIR_IN 0x00000040 /* Data direction (01: DATA IN) */ 

((define CAM_DIR_OUT 0x00000080 /* Data direction (10: DATA OUT) */ 

((define CAM_DIR_NONE OxOOOOOOCO /* Data direction (11: no data) */ 

((define CAM_DIS_AUTOSENSE 0x00000020 /* Disable autosense feature */ 

((define CAM_SCATTER_VALID 0x00000010 /* Scatter/gather list is valid */ 
((define CAM_DIS_CALLBACK 0x00000008 /* Disable callback feature */ 

((define CAM_CDB_LINKED 0x00000004 /* The CCB contains a linked CDB */ 
((define CAM_QUEUE_ENABLE 0x00000002 /* SIM queue actions are enabled */ 
((define CAM_CDB_POINTER 0x00000001 /* The CDB field contains a pointer */ 

((define CAM DIS DISCONNECT 0x00008000 /* Disable disconnect */ 

((define CAM_INITIATE_SYNC 0x00004000 /* Attempt Sync data xfer, and SDTR */ 
((define CAM_DIS_SYNC 0x00002000 /* Disable sync, go to async */ 

((define CAM_SIM_QHEAD 0x00001000 /* Place CCB at the head of SIM Q */ 

((define CAM_SIM_QFREEZE 0x00000800 /* Return the SIM Q to frozen state */ 
((define CAM SIM QFRZDIS 0x00000400 /* Disable the SIM Q frozen state */ 

((define CAM_ENG_SYNC 0x00000200 /* Flush resid bytes before cmplt */ 

((define CAM_ENG_SGLIST 0x00800000 /* The SG list is for the HBA engine */ 

((define CAM_CDB_PHYS 0x00400000 /* CDB pointer is physical */ 

((define CAM_DATA_PHYS 0x00200000 /* SG/Buffer data ptrs are physical */ 
((define CAM_SNS_BUF_PHYS 0x00100000 /* Autosense data ptr is physical */ 

((define CAM_MSG_BUF_PHYS 0x00080000 /* Message buffer ptr is physical */ 

((define CAM_NXT_CCB_PHYS 0x00040000 /* Next CCB pointer is physical */ 
((define CAM_CALLBCK_PHYS 0x00020000 /* Callback func ptr is physical */ 
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[(define CAM_DATAB_VALID 0x80000000 /* Data buffer valid */ 

#define CAM_STATUS_VALID 0x40000000 /* Status buffer valid */ 

((define CAM_MSGB_VALID 0x20000000 /* Message buffer valid */ 

((define CAM_TGT_PHASE_MODE 0x08000000 /* The SIM will run in phase mode */ 
#define CAM_TGT_CCB_AVAIL 0x04000000 /* Target CCB available */ 

[(define CAM_DIS_AUTODISC 0x02000000 /* Disable autodisconnect */ 

((define CAM_DIS_AUTOSRP 0x01000000 /* Disable autosave/restore ptrs */ 

/* . V 

/* Defines for the SIM/HBA queue actions. These value are used in the 
SCSI I/O CCB, for the queue action field. [These values should match the 
defines from some other include file for the SCSI message phases. We may 
not need these definitions here. ] */ 


[[define CAMSIMPLEQTAG 0x20 /* Tag for a simple queue */ 

[[define CAM_HEAD_QTAG 0x21 /* Tag for head of queue */ 

[[define CAM_ORDERED_QTAG 0x22 /* Tag for ordered queue */ 

/* .-. V 

/* Defines for the timeout field in the SCSI I/O CCB. At this time a 
value of OxF-F indicates a infinite timeout. A value of 0x0-0 
indicates that the SIM's default timeout can take effect. */ 

[[define CAM_TIME_DEFAULT 0x00000000 /* Use SIM default value */ 

[[define CAM_TIME_INFINITY OxFFFFFFFF /* Infinite timeout for I/O */ 

/* . V 


/* Defines for the Path Inquiry CCB fields. */ 


#define 


CAMJVERSION 0x25 

/* 

Binary value for the current ver */ 

[[define 

PI_ 

_MDP_ABLE 

0x80 

/* 

Supports 

MDP message */ 


#define 

PI . 

_WIDE_32 

0x40 

/* 

Supports 

32 bit wide SCSI 

V 

[[define 

PI . 

_WIDE_16 

0x20 

/* 

Supports 

16 bit wide SCSI 

V 

[[define 

pi _ 

_SDTR_ABLE 

0x10 

/* 

Supports 

SDTR message */ 


#define 

pi _ 

_LINKED_CDB 

0x08 

/* 

Supports 

linked CDBs */ 


([define 

p I_ 

_TAG_ABLE 

0x02 

/* 

Supports 

tag queue message 

V 

[[define 

PI _ 

_SOFT_RST 

0x01 

/* 

Supports 

soft reset */ 


[[define 

PIT_PROCESSOR 

0x80 

/* 

Target mode processor mode 

V 


[[define PIT_PHASE0x40 /* Target mode phase cog. mode */ 


[[define PIM_SCANHILO 0x80 
#define PIM_NOREMOVE 0x40 
[[define PIM NOINQUIRY 0x20 


/* Bus scans from ID 7 to ID 0 */ 

/* Removable dev not included in scan 
/* Inquiry data not kept by XPT */ 


/* 


/* Defines for Asynchronous Callback CCB fields. */ 


[[define AC 
[[define AC 
[(define AC_ 
[(define AC 
[[define AC_ 
[[define AC_ 
[[define AC 


FOUND_DEVICES 0x80 
SIM_DEREGISTER 0x40 
SIM_REGISTER 0x20 

SENT_BDR 0x10 

SCSI_AEN 0x08 

UNSOL_RESEL 0x02 /* A 

BUS RESET 0x01 


/* During a rescan new device found */ 
/* A loaded SIM has de-registered */ 

/* A loaded SIM has registered */ 

/* A BDR message was sent to target */ 
/* A SCSI AEN has been received */ 
unsolicited reselection occurred */ 

/* A SCSI bus RESET occurred */ 


/* .-.V 

/* Typedef for a scatter/gather list element. */ 
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typedef struct sg_elem 

{ 

u_char *cam_sg_address; /* Scatter/Gather address */ 

u_long cam_sg_count; /* Scatter/Gather count */ 

} SG_ELEM; 

/*.-. V 

/* Defines for the HBA engine inquiry CCB fields. */ 

#define EIT_BUFFER 0x00 /* Engine type: Buffer memory */ 

^define EIT__LOSSLESS 0x01 /* Engine type: Lossless compression */ 

#define EIT_LOSSLY 0x02 /* Engine type: Lossly compression */ 

^define EIT_ENCRYPT 0x03 /* Engine type: Encryption */ 

fldefine EAD VUNIQUE 0x00 /* Eng algorithm ID: vendor unique */ 

#define EAD_LZ1V10x00 /* Eng algorithm ID: LZl var. 1*/ 

fldefine EAD_LZ2V10x00 /* Eng algorithm ID: LZ2 var. 1*/ 

#define EAD_LZ2V20x00 /* Eng algorithm ID: LZ2 var. 2*/ 

/* 

/* 

/* Unix OSD defines and data structures. */ 

^define INQLEN 36 /* Inquiry string length to store. */ 

Sdefine CAM_SUCCESS 0 /* For signaling general success */ 

#define CAM_FAILURE 1 /* For signaling general failure */ 

#define CAM_FALSE0 /* General purpose flag value */ 

#define CAMTRUE 1 ■/* General purpose flag value */ 

#define XPT_CCB_INVALID -1 /* for signaling a bad CCB to free */ 

/* General Union for Kernel Space allocation. Contains all the 
possible CCB structures. This union should never be used for 
manipulating CCB's its only use is for the allocation and deallocation 
of raw CCB space. */ 

typedef union ccb_size_union 

{ 

CCB_SCSIIO csio; /* Please keep this first, for debug/print */ 
CCB_GETDEV cgd; 

CCBJPATHINQ cpi; 

CCB_RELSIM crs; 

CCB_SETASYNC csa; 

CCB_SETDEV csd; 

CCB_ABORT cab; 

CCB_RESETBUS crb; 

CCB_RESETDEV crd; 

CCB_TERMIO ctio; 

CCB_EN_LUN cel; 

CCB_ENG_INQ cei; 

CCB_ENG_EXEC cee; 

} CCB_SIZE_UNION; 

/* The typedef for the Async callback information. This structure is 
used to store the supplied info from the Set Async Callback CCB, in 
the EDT table in a linked list structure. */ 

typedef struct async_info 

{ 

struct async_info *cam_async_next; /* pointer to the next structure */ 
u_long cam_event_enable; /* Event enables for Callback resp */ 


V 

V 
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void (*cam_async_func)(); /* Async Callback function address */ 

u_long cam_async_blen; /* Length of "information" buffer */ 
u_char *cam_async_ptr; /* Address for the "information */ 

} ASYNC_INFO; 

/* The CAM EDT table contains the device information for all the 
devices, SCSI ID and LUN, for all the SCSI busses in the system. The 
table contains a CAM_EDT_ENTRY structure for each device on the bus. 

*/ 

typedef struct cam_edt_entry 

l 

long cam_tlun_found; /* Flag for the existence of the target/LUN */ 
ASYNC_INFO *cam_ainfo; /* Async callback list info for this B/T/L */ 
u_long cam_owner_tag; /* Tag for the peripheral driver's ownership */ 
char caminqdata[ INQLEN ]; /* storage for the inquiry data */ 

} CAM_EDT_ENTRY; 

/* . V 
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Summary of Device Driver Routines 




Table B-l summarizes the routines used by all device drivers. The table has the 
following columns: 

• Routine - the driver routine name. 

• Structure/file - the structure or file where you define the driver routine entry point 

• Character - an X in this column indicates the routine is applicable to a character 
device. 

• Block - an X in this column indicates the routine is applicable to a block device. 
N/A indicates not applicable. 

For convenience, the routines appear in alphabetical order. 

Note 

The psize routine is no longer used. Previously, the routine 
determined the location on the disk where ULTRLX should perform a 
dump. It has been superseded by driver ioctl calls that obtain disk 
geometry information. 


Table B-1: Summary of Device Driver Routines 


Routine 

Structure/File 

Character 

Block 

attach 

Peripheral driver 

X 

X 

close 

cdevsw bdevsw 

X 

X 

interrupt 

System configuration file 

X 

X 

ioctl 

cdevsw bdevsw 

X 

X 

mmap 

cdevsw 

X 

N/A 

open 

cdevsw bdevsw 

X 

X 

probe 

SIM 

X 

X 

read 

cdevsw 

X 

N/A 

reset 

cdevsw 

X 

N/A 

select 

cdevsw 

X 

N/A 

slave 

Peripheral driver 

X 

X 

stop 

cdevsw 

X 

N/A 

strategy 

cdevsw bdevsw 

X 

X 

write 

cdevsw 

X 

N/A 







SCSI/CAM Routines in ULTRIX Reference 

Page Format 



This appendix contains a description of each of the routines described in this guide, 
in ULTRIX reference page format. The routines are included in alphabetical order. 



Name 


camjogger - allocates a system error log buffer and fills in a uerf error log packet 


Syntax 

u Jong camjogger (cam_err_hdr, bus, target, lun) 

CAM_ERR_HDR *cam_err_hdr; 

long bus; 

long target; 

long lun; 


Arguments 

camerrjidr 

bus 

target 

lun 


Description 

The cam_logger routine allocates a system error log buffer and fills in a uerf 
error log packet. The routine fills in the bus, target, and LUN information from the 
Error Header Structure passed to it and copies the Error Header Structure and the 
Error Entry Structures and data to the error log buffer. 

Return Value 

None 


Pointer to the Error Header Structure. 
SCSI target’s bus controller number. 
SCSI target’s ID number. 

SCSI target’s logical unit number. 


C-2 SCSI/CAM Routines in ULTRIX Reference Page Format 



Name 


ccfg_attach - calls a SCSI/CAM peripheral driver’s attach routine after a match on 
the cpd_name member of the CAM_PERIPHERAL_DRIVER structure is found 


Syntax 

int ccfg_attach(w/) 

register struct uba_device *«/; 


Arguments 

ui Pointer to the device information contained in the uba device structure. 


Description 

The ccfg_attach routine calls a SCSI/CAM peripheral driver’s attach routine 
after a match on the cpd name member of the CAM_PERIPHERAL_DRIVER 
structure is found. The routine is called during autoconfiguration. The 
ccf g_attach routine locates the configured driver in the SCSI/CAM peripheral 
driver configuration table. If the driver is located successfully, the SCSI/CAM 
peripheral driver’s attach routine is called with a pointer to the unit information 
structure for the device from the kernel uba device structure. The SCSI/CAM 
peripheral driver’s attach routine performs its own attach initialization. 

Return Value 

0 = success 
1 = failure 

The return value is ignored by autoconfiguration code. 
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Name 


ccfg_edtscan - issues SCSI INQUIRY commands to all possible SCSI targets and 
LUNs attached to the buses 


Syntax 

ujong ccfg_edtscan (scanjype, bus, target, lun ) 
long scanjype; 
long bus; 
long target; 


long lun; 


Arguments 

scanjype 

Types of scans are: FULL, which traverses the CAMJEDTJENTRY 
structure and sends an INQUIRY command to each target and LUN; 
PARTIAL, which sends an INQUIRY command only to targets and 
LUNs flagged as “not found”; or SINGLE, which sends an INQUIRY 
command to the selected bus, target, and LUN passed as arguments. 

bus 

SCSI target’s bus controller number. 

target 

SCSI target’s ID number. 

lun 

SCSI target’s logical unit number. 


Description 

The ccf g_edtscan routine issues SCSI INQUIRY commands to all possible 
SCSI targets and LUNs attached to the buses. The routine uses the CAM subsystem 
in the normal manner by sending SCSI I/O CCBs to the SIMs. The INQUIRY data 
returned is stored in the EDT structures and the cam_tlun_found flag is set. 

This routine can be called by the SCSI/CAM peripheral device drivers to reissue a 
full, partial, or single bus scan command. 


Return Value 

CAM_SUCCESS 

CAMJFAILURE 
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Name 


ccfg_slave - calls a SCSI/CAM peripheral driver’s slave routine after a match on the 
cpd_name member of the CAM_PERIPHERAL_DRIVER structure is found 


Syntax 

int ccfg_slave(ia) 
register struct uba_device *«/; 
caddr_t csr; 


Arguments 

ui Pointer to the device information contained in the uba_devi.ce structure. 
csr The virtual address of the control and status register (CSR) address. 

Description 

The ccfg_slave routine calls a SCSI/CAM peripheral driver’s slave routine after 
a match on the cpd name member of the CAM_PERIPHERAL_DRIVER structure 
is found. The routine is called during autoconfiguration. The ccfg_slave routine 
locates the configured driver in the SCSI/CAM peripheral driver configuration table. 
If the driver is located successfully, the SCSI/CAM peripheral driver’s slave routine 
is called with a pointer to the unit information structure for the device from the 
kernel uba_device structure and the virtual address of its control and status 
register (CSR). The SCSI/CAM peripheral driver’s slave routine performs its own 
slave initialization. 


Return Value 

0 = slave is alive 
1 * slave is not alive 
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Name 


ccmn_DoSpecialCmd - provides a simplified interface to the special command 
routine 


Syntax 

ccmn_DoSpecialCmd(dev, cmd, data, flags, ccb, sflags ) 

dev_t dev, 

int cmd; 

caddr_t data; 

int flags; 

CCB.SCSIIO *ccb; 
int sflags; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

cmd The ioctl command, UAGT_CAM_IO. 

data The user data buffer. 

flags Flags set when a file is open. 

ccb Pointer to the SCSI I/O CCB structure. This field is optional. 

sflags SCSI/CAM special I/O control flags. The available flags are: 

Flag Name Description 

SA_NO_ERROR_RECOVERY Do not perform error recovery 

SA_no_error_logging Do not log error messages 

SA_no_SLEEP_intr Do not allow sleep interrupts 

SA_N0_SIMQ_thaw Leave SIM queue frozen when 

there are errors 


Description 

The ccmn DoSpecialCmd routine provides a simplified interface to the special 
command routine. The routine prepares for and issues special commands. 

Return Value 

The ccmn_DoSpecialCmd routine returns a value of 0 (zero) upon successful 
completion. It returns the appropriate error code on failure. 
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Name 


ccmn_SysSpecialCmd - lets a system request issue SCSI I/O commands to the 
SCSI/CAM special I/O interface 

Syntax 

ccmn_SysSpecialCmd(dev, and, data, flags, ccb, sflags) 

dev_t dev, 

int cmd; 

caddr_t data; 

int flags; 

CCB_SCSIIO *ccb; 

sflags; 


The major/minor device number pair that identifies the bus number, 
target ID, and LUN associated with this SCSI device. 

The ioctl command, UAGT_CAM_IO. 

The user data buffer. 

Flags set when a file is open. 

Pointer to the SCSI I/O CCB structure. This field is optional. 
SCSI/CAM special I/O control flags. The available flags are: 


Flag Name Description 

Sa_no_e R ROR_R ECOVERY Do not perform error recovery 

SA_NO_ERROR_LOGGlNG Do not log error messages 

SA_no_SLEEP_intr Do not allow sleep interrupts 

SA_NO_S imq_thaw Leave SIM queue frozen when 

there are errors 


The ccmn_SysSpecialCmd routine lets a system request issue SCSI I/O 
commands to the SCSI/CAM special I/O interface. This permits existing SCSI 
commands to be issued from within kernel code. 

Return Value 

The ccmn_DoSpecialCmd routine returns a value of 0 (zero) upon successful 
completion. It returns the appropriate error code on failure. 


int 

Arguments 

dev 

cmd 

data 

flags 

ccb 

sflags 


Description 
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Name 


ccmn_abort_ccb_bld - creates an ABORT CCB and sends it to the XPT 

Syntax 

ccmn_abort_ccb_bld(fitev, camJlags , abort_ccb ) 
dev_t dev, 

u_long camJlags; 

CCBJHEADER *abort_ccb; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

camJlags The cam Jlags flag names and their bit definitions are listed in the table 
that follows: 


Flag Name 

Description 

CAM_DIR_RESV 

Data direction (00: reserved) 

CAM_DIR_IN 

Data direction (01: DATA IN) 

CAM_DIR_OUT 

Data direction (10: DATA OUT) 

CAM_DIR_NONE 

Data direction (11: no data) 

CAM_DIS_AUTOS ENS E 

Disable autosense feature 

CAM_SCATTER_VALID 

Scatter/gather list is valid 

CAM_DIS_CALLBACK 

Disable callback feature 

CAM_CDB_LINKED 

CCB contains linked CDB 

CAM_QUEUE_ENABLE 

SIM queue actions are enabled 

CAM_CDB_POINTER 

CDB field contains pointer 

CAM_DIS_DISCONNECT 

Disable disconnect 

CAM_INITIATE_SYNC 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 

CAM_DIS_SYNC 

Disable synchronous mode, go to 
asynchronous 

CAM_SIM_QHEAD 

Place CCB at head of SIM queue 

CAM_SIM_QFREEZE 

Return SIM queue to frozen state 

CAM_ENG_SYNC 

Flush residual bytes from HBA 
data engine before terminating I/O 

CAM_ENG_SGLIST 

Scatter/gather list is for HBA 
engine 

CAM_CDB_PHYS 

CDB pointer is physical address 

CAM_DATA_PHYS 

Scatter/gather/buffer data pointers 
are physical address 
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Description 


Flag Name 

CAM_SNS_BUF_PHYS Autosense data pointer is physical 

address 

CAM_MSG_BUF_PHYS Message buffer pointer is physical 

address 

CAM_nxt_CCB_p HY S Next CCB pointer is physical 

address 

CAM_CALLBCK_PHYS Callback function pointer is 

physical address 

CAM DATAB VALID Data buffer valid 

CAM_STATUS_VALID Status buffer valid 

CAM_MSGB_VALID Message buffer valid 

CAM_TGT_PHASE_MODE SIM will run in phase mode 
CAM_TGT_CCB_AVAIL Target CCB available 

CAM_DIS_AUT0DISC Disable autodisconnect 

CAM_DlS_AUTOSRP Disable autosave/restore pointers 

abort_ccb Pointer to the CAM Control Block (CCB) header structure to abort. 

Description 

The ccmn_abort_ccb_bld routine creates an ABORT CCB and sends it to the 
XPT. The routine calls the ccmn_get_ccb routine to allocate a CCB structure 
and fill in the common portion of the CCB header. The routine fills in the address of 
the CCB to be aborted and calls the ccmn_send_ccb routine to send the CCB 
structure to the XPT. The request is carried out immediately, so it is not placed on 
the device driver’s active queue. 

Return Value 

CCB_ABORT pointer 

See Also 

ccmn_get_ccb, ccmn_send_ccb 
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Name 


ccmn_abort_que - sends an ABORT CCB request for each SCSI I/O CCB on the 
active queue 

Syntax 

ccmn_abort_que(pfO 

PDRV_DEVICE *pd; 


Arguments 

pd Pointer to the CAM Peripheral Device Structure allocated for each SCSI 
device in the system. 

Description 

The ccmn_abort_que routine sends an ABORT CCB request for each SCSI I/O 
CCB on the active queue. This routine must be called with the Peripheral Device 
Structure locked. 

The ccmn_abort_que routine calls the ccmn_abort_ccb_bld routine to 
create an ABORT CCB for the first active CCB on the active queue and send it to 
the XPT. It calls the ccmn_send_ccb routine to send the ABORT CCB for each 
of the other CCBs on the active queue that are marked as active to the XPT. The 
ccmn_abort_que routine then calls the ccmn_rel_ccb routine to return the 
ABORT CCB to the XPT. 


Return Value 

None 


See Also 

ccmn abort ccb bid, ccmn rel ccb, ccmn send_ccb 
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Name 


ccmn_bdr_ccb_bld - creates a BUS DEVICE RESET CCB and sends it to the XPT 


Syntax 

ccmn_bdr_ccb_bld(dev, camJlags ) 
dev_t dev; 
u_long camJlags; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

camJlags The cam Jags flag names and their bit definitions are listed in the table 


that follows: 


Flag Name 

Description 

CAM_DIR_RESV 

Data direction (00: reserved) 

CAM_DIR_IN 

Data direction (01: DATA IN) 

CAM_DIR_OUT 

Data direction (10: DATA OUT) 

CAM_DIR_NONE 

Data direction (11: no data) 

CAM_DIS_AUTOS ENS E 

Disable autosense feature 

CAM_SCATTER_VALID 

Scatter/gather list is valid 

CAM_DIS_CALLBACK 

Disable callback feature 

CAM_CDB_LINKED 

CCB contains linked CDB 

CAM_QUEUE_ENABLE 

SIM queue actions are enabled 

CAM_CDB_POINTER 

CDB field contains pointer 

CAM_DIS_DISCONNECT 

Disable disconnect 

CAM_INITIATE_SYNC 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 

CAM_DIS_SYNC 

Disable synchronous mode, go to 
asynchronous 

CAM_SIM_QHEAD 

Place CCB at head of SIM queue 

CAM_SIM_QFREEZE 

Return SIM queue to frozen state 

CAM_ENG_SYNC 

Flush residual bytes from HBA 
data engine before terminating I/O 

CAM_ENG_SGLIST 

Scatter/gather list is for HBA 
engine 

CAM_CDB_PHYS 

CDB pointer is physical address 

CAM_DATA_PHYS 

Scatter/gather/buffer data pointers 
are physical address 

CAM_SNS_BUF_PHYS 

Autosense data pointer is physical 
address 
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Flag Name 

Description 

CAM_MSGJ3UF_PHYS 

Message buffer pointer is physical 
address 

CAM_NXT_CCB_PHYS 

Next CCB pointer is physical 
address 

CAM_CALLBCK_PHYS 

Callback function pointer is 
physical address 

CAM_DATAB_VALID 

Data buffer valid 

CAM_STATUS_VALID 

Status buffer valid 

CAM_MS GB_VALID 

Message buffer valid 

CAM__TGT_P HAS E_MODE 

SIM will run in phase mode 

CAM_TGT_CCB_AVAIL 

Target CCB available 

CAM_DIS_AUTODISC 

Disable autodisconnect 

CAM_DIS_AUTOSRP 

Disable autosave/restore pointers 


Description 

The ccmn_bdr_ccb_bld routine creates a BUS DEVICE RESET CCB and sends 
it to the XPT. The routine calls the ccmn_get_ccb routine to allocate a CCB 
structure and fill in the common portion of the CCB header. The routine calls the 
ccmn_send_ccb routine to send the CCB structure to the XPT. The request is 
carried out immediately, so it is not placed on the device driver’s active queue. 


Return Value 

CCB_RESETDEV pointer 


See Also 

ccmn_get_ccb, ccmn_send_ccb 
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Name 


ccmn_br_ccb_bld - creates a BUS RESET CCB and sends it to the XPT 


Syntax 

ccmn_br_ccb_bld(rfev, cam Jiags) 
dev_t dev, 
u_long camjlags', 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

camJiags The cam Jiags flag names and their bit definitions are listed in the table 


that follows: 


Flag Name 

Description 

CAM_DIR_RESV 

Data direction (00: reserved) 

CAM_DIR_IN 

Data direction (01: DATA IN) 

CAM_DIR_OUT 

Data direction (10: DATA OUT) 

CAM_DIR_NONE 

Data direction (11: no data) 

CAM_DIS_AUTOSENSE 

Disable autosense feature 

CAM_SCATTER_VALID 

Scatter/gather list is valid 

CAM_DIS_CALLBACK 

Disable callback feature 

CAM_CDB_LINKED 

CCB contains linked CDB 

CAM_QUEUE_ENABLE 

SIM queue actions are enabled 

CAM_CDB_POINTER 

CDB field contains pointer 

CAM_DIS_DISCONNECT 

Disable disconnect 

CAM_INITIATE_SYNC 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 

CAM_DIS_SYNC 

Disable synchronous mode, go to 
asynchronous 

CAM_SIM_QHEAD 

Place CCB at head of SIM queue 

CAM_SIM_QFREEZE 

Return SIM queue to frozen state 

CAM_ENG_SYNC 

Flush residual bytes from HBA 
data engine before terminating I/O 

CAM_ENG_SGLIST 

Scatter/gather list is for HBA 
engine 

CAM_CDB_PHYS 

CDB pointer is physical address 

CAM_DATA_PHYS 

Scatter/gather/buffer data pointers 
are physical address 

CAM_SNS_BUF_PHYS 

Autosense data pointer is physical 
address 
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Flag Name 

Description 

CAM_MSG_BUF_PHYS 

Message buffer pointer is physical 
address 

CAM_NXT_CCB_PHYS 

Next CCB pointer is physical 
address 

CAM_CALLBCK_PHYS 

Callback function pointer is 
physical address 

CAM_DATAB_VALID 

Data buffer valid 

CAM_S TATUS_VALID 

Status buffer valid 

CAM_MS GB_VALID 

Message buffer valid 

CAM_TGT_PHAS E_MODE 

SIM will run in phase mode 

CAM_TGT_CCB_AVAIL 

Target CCB available 

CAM_DIS_AUTODISC 

Disable autodisconnect 

CAM_DIS_AUTOSRP 

Disable autosave/restore pointers 


Description 

The ccmn_br_ccb_bld routine creates a BUS RESET CCB and sends it to the 
XPT. The routine calls the ccmn_get_ccb routine to allocate a CCB structure 
and fill in the common portion of the CCB header. The routine calls the 
ccmn_send_ccb routine to send the CCB structure to the XPT. The request is 
carried out immediately, so it is not placed on the device driver’s active queue. 

Return Value 

CCB_RESETBUS pointer 

See Also 

ccmn_get_ccb, ccmn_send_ccb 
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Name 


ccmn_ccb_status - assigns individual CAM status values to generic categories 


Syntax 

ccmn_ccb_status(cc&) 

CCB_HEADER *ccb; 


Arguments 

ccb Pointer to the CAM Control Block (CCB) header structure whose status is to 
be categorized. 

Description 

The ccmn_ccb_status routine assigns individual CAM status values to generic 
categories. The following table shows the returned category for each CAM status 
value: 


CAM Status 

Assigned Category 

CAM REQ INPROG 

CAT INPROG 

CAM REQ CMP 

CAT CMP 

CAM REQ ABORTED 

CAT_ABORT 

CAM UA ABORT 

CAT ABORT 

CAM REQ CMP ERR 

CAT CMP ERR 

CAM BUSY 

CAT BUSY 

CAM REQ INVALID 

CAT CCB ERR 

CAM PATH INVALID 

CAT NO DEVICE 

CAM DEV NOT THERE 

CAT NO DEVICE 

CAM UA TERMIO 

CAT ABORT 

CAM SEL TIMEOUT 

CAT DEVICE ERR 

CAM CMD TIMEOUT 

CAT DEVICE ERR 

CAM MSG REJECT REC 

CAT DEVICE ERR 

CAM SCSI BUS RESET 

CAT RESET 

CAM UNCOR PARITY 

CAT DEVICE ERR 

CAM AUTOSENSE FAIL 

CAT BAD AUTO 

CAM NO HBA 

CAT NO DEVICE 

CAM DATA RUN ERR 

CAT DEVICE ERR 

CAM UNEXP BUSFREE 

CAT DEVICE ERR 

CAM SEQUENCE FAIL 

CAT DEVICE ERR 

CAM CCB LEN ERR 

CAT CCB ERR 

CAM PROVIDE FAIL 

CAT CCB ERR 

CAM BDR SENT 

CAT RESET / 

CAM REQ TERMIO 

CAT ABORT 

CAM LUN INVALID 

CAT NO DEVICE 

CAM TID INVALID 

CAT NO DEVICE 

CAM FUNC NOTAVAIL 

CAT CCB ERR 

CAM NO NEXUS 

CAT NO DEVICE 

CAM IID INVALID 

CAT NO DEVICE 

CAM SCSI BUSY 

CAT SCSI BUSY 

Other 

CAT UNKNOWN 
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Return Value 

The following categories can be returned: 


CAM Status 

Assigned Category 

CAT_INPROG 

Request is in progress. 

CAT_CMP 

Request has completed without error. 

CAT CMP ERR 

Request has completed with error. 

CAT_ABORT 

Request either has been aborted or terminated, or it 
cannot be aborted or terminated. 

CAT BUSY 

CAM is busy. 

CAT SCSI BUSY 

SCSI is busy. 

CAT NO DEVICE 

No device at address specified in request. 

CAT DEVICE ERR 

Bus or device problems. 

CAT BAD AUTO 

Invalid autosense data. 

CAT CCB ERR 

Invalid CCB. 

CAT RESET 

Unit or bus has detected a reset condition. 

CAT_UNKNOWN 

Invalid CAM status. 
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Name 


ccmn_ccbwait - sleeps waiting for a SCSI I/O CCB request to complete 


Syntax 

ccmn_ccbwait(cd>, priority) 
register CCBJSCSIIO *ccb\ 
register int Apriority; 


Arguments 

ccb Pointer to the CCB on which to wait. 
priority Software priority at which to sleep. 


Description 

The ccmn_ccbwait routine sleeps waiting for a SCSI I/O CCB request to 
complete. If the priority is greater than PZERO, the ccmn_ccbwait routine 
sleeps at an interruptible priority in order to catch signals. 


Return Value 

EINTR - Sleep was interrupted due to receiving a signal 
0 - CCB has completed 
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Name 


ccmn_close_unit - handles the common close for all SCSI/CAM peripheral device 
drivers 

Syntax 

ccmn_close_unit(fitev) 

dev_t dev. 


Arguments 

dev The major/minor device number pair that identifies the bus number, target 
ID, and LUN associated with this SCSI device. 

Description 

The ccmn__close_unit routine handles the common close for all SCSI/CAM 
peripheral device drivers. It sets the open count to zero. 

Return Value 

None 

See Also 

ccmn_open_unit 
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Name 


ccmn_errlog - reports error conditions for the SCSI/CAM peripheral device driver 

Syntax 

ccmn_errlog {funcstr, opt_str, flags, ccb, dev, mused) 
u_char *fimc_str; 

u_char *opt_str; 

ujong flags; 

CCB_HEADER *ccb; 
dev_t dev ; 

u_char *unused; 


Arguments 

func_str Pointer to function in which the error was detected. 

optjstr Pointer to optional logging string. 

flags Flags for peripherial drivers error types. The flags are: 

CAM_INFORMATIONAL; CAM_SOFTERR; CAM_HARDERR; 

CAM_SOFTWARE; and CAM_DUMP_ALL. They are defined in the 
/usr/sys/h/cam_logger. h file. 

ccb Pointer to the CAM Control Block (CCB) header structure. 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

unused Unused. It is needed to match the number of arguments expected by the 
CAM_ERROR macro, which is defined in the 
/usr/sys/io/cam/cam_errlog. h file 

Description 

The ccmn_errlog routine reports error conditions for the SCSI/CAM peripheral 
device driver. The routine is passed a pointer to the name of the function in which 
the error was detected. The routine builds informational strings based on the error 
condition. 

Return Value 

None 
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Name 


ccmn_gdev_ccb_bld - creates a GET DEVICE TYPE CCB and sends it to the XPT 


Syntax 

ccmn_gdev_ccb_bld(6tev, camJiags , inq addr ) 
dev_t dev; 
u_long cam Jiags; 
u_char *inq_addr; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

cam Jiags The cam Jags flag names and their bit definitions are listed in the table 
that follows: 


Flag Name 

Description 

CAM_DIR_RESV 

Data direction (00: reserved) 

CAM_DIR_IN 

Data direction (01: DATA IN) 

CAM_DIR_OUT 

Data direction (10: DATA OUT) 

CAM_DIR_NONE 

Data direction (11: no data) 

CAM_DIS_AUTOS ENS E 

Disable autosense feature 

CAM_S CATT E R_VALID 

Scatter/gather list is valid 

CAM_DIS_CALLBACK 

Disable callback feature 

CAM_CDB_LINKED 

CCB contains linked CDB 

CAM_QUEUE_ENABLE 

SIM queue actions are enabled 

CAM_CDB_POINTER 

CDB field contains pointer 

CAM_DIS_DISCONNECT 

Disable disconnect 

CAM_INITIATE_SYNC 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 

CAM_DIS_SYNC 

Disable synchronous mode, go to 
asynchronous 

CAM_SIM_QHEAD 

Place CCB at head of SIM queue 

CAM_SIM_QFREEZE 

Return SIM queue to frozen state 

CAM_ENG_SYNC 

Flush residual bytes from HBA 
data engine before terminating I/O 

CAM_ENG_SGLIST 

Scatter/gather list is for HBA 
engine 

CAM_CDB_PHYS 

CDB pointer is physical address 

CAM_DATA_PHYS 

Scatter/gather/buffer data pointers 
are physical address 
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Flag Name 

Description 

CAM_SNS_BUF_PHYS 

Autosense data pointer is physical 
address 

CAM_MSG_BUF_PHYS 

Message buffer pointer is physical 
address 

CAM_NXT_CCB_P HY S 

Next CCB pointer is physical 
address 

CAM_CALLBCK_PHYS 

Callback function pointer is 
physical address 

CAM_DATAB_VALID 

Data buffer valid 

CAM_STATUS_VALID 

Status buffer valid 

CAM_MS GB_VALID 

Message buffer valid 

CAM_TGT_PHASE_MODE 

SIM will run in phase mode 

CAM_TGT_CCB_AVAIL 

Target CCB available 

CAM_DIS_AUTODISC 

Disable autodisconnect 

CAM_DIS_AUTOSRP 

Disable autosave/restore pointers 


inq_addr Pointer to the address for Inquiry data returned. 

Description 

The ccmn_gdev_ccb_bld routine creates a GET DEVICE TYPE CCB and sends 
it to the XPT. The routine calls the ccmn_get_ccb routine to allocate a CCB 
structure and fill in the common portion of the CCB header. The 
ccmn_gdev_ccb_bld routine calls the ccmn_send_ccb routine to send the 
CCB structure to the XPT. The request is carried out immediately, so it is not placed 
on the device driver’s active queue. 

Return Value 

CCB_GETDEV pointer 


See Also 

ccmn_get_ccb, ccmn_send_ccb 
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Name 


ccmn_get_bp - allocates a buf structure 


Syntax 

ccmn_get_bp() 


Arguments 

None 


Description 

The ccmn_get_bp routine allocates a buf structure. This function must not be 
called at interrupt context. The function may sleep waiting for resources. 


Return Value 

Pointer to buf structure. This pointer may be NULL. 
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Name 


ccmn_get_ccb - allocates a CCB and fills in the common portion of the CCB header 


Syntax 

ccmn_get_ccb ( dev, funcjcode, cam Jlags, ccbjeri) 

dev_t dev, 

u_char Juncjcode; 

u_long camJlags; 

u_short ccbjen ; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

funcjcode The XPT function code for the CCB. See American National Standard 
for Information Systems, SCSI-2 Common Access Method: Transport 
and SCSI Interface Module, working draft, X3T9.2/90-186, Section 
8.1.2, for a list of the function codes. 

camJlags The cam Jlags flag names and their bit definitions are listed in the table 
that follows: 


Flag Name Description 


CAM_DIR_RESV 
CAM_DIR_IN 
CAM_DIR_OUT 
CAM_DIR_NONE 
CAM_DIS_AUTOSENS E 
CAM_SCATTER_VALID 
CAM_DIS_CALLBACK 
CAM_CDB_LINKED 
CAM_QUEUE_ENABLE 
CAM_CDB_POINTER 
CAM_DIS_DISCONNECT 
CAM_INITIATE_SYNC 

CAM_DIS_SYNC 

CAM_SIM_QHEAD 
CAM_SIM_QFREEZE 
CAM ENG SYNC 


Data direction (00: reserved) 

Data direction (01: DATA IN) 
Data direction (10: DATA OUT) 
Data direction (11: no data) 
Disable autosense feature 
Scatter/gather list is valid 
Disable callback feature 
CCB contains linked CDB 
SIM queue actions are enabled 
CDB field contains pointer 
Disable disconnect 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 

Disable synchronous mode, go to 
asynchronous 

Place CCB at head of SIM queue 

Return SIM queue to frozen state 

Flush residual bytes from HBA 
data engine before terminating I/O 
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Flag Name 

Description 

CAM_ENG_SGLIST 

Scatter/gather list is for HBA 
engine 

CAM_CDB_PHYS 

CDB pointer is physical address 

CAM_DATA_PHYS 

Scatter/gather/buffer data pointers 
are physical address 

CAM_SNS_BUF_PHYS 

Autosense data pointer is physical 
address 

CAM_MSG_BUF_PHYS 

Message buffer pointer is physical 
address 

CAM_NXT_CCB_P HY S 

Next CCB pointer is physical 
address 

CAM__CALLBCK_PHYS 

Callback function pointer is 
physical address 

CAM_DATAB__VAL ID 

Data buffer valid 

CAM_S TATD S _VALID 

Status buffer valid 

CAM_MSGB_VALID 

Message buffer valid 

CAM_TGT_PHAS E_MODE 

SIM will run in phase mode 

CAM_TGT_CCB_AVAIL 

Target CCB available 

CAM_DIS_AUTODISC 

Disable autodisconnect 

CAM_DIS_AUTOSRP 

Disable autosave/restore pointers 


ccbJen The length of the CCB. 

Description 

The ccmn_get_ccb routine allocates a CCB and fills in the common portion of 
the CCB header. The routine calls the xpt_ccb_alloc routine to allocate a CCB 
structure. The ccmn_get_ccb routine fills in the common portion of the CCB 
header and returns a pointer to that CCB_HEADER. 


Return Value 

Pointer to newly allocated CCB header. 


See Also 

xpt_ccb_alloc 
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Name 


ccmn_get_dbuf - allocates a data buffer area of the size specified by calling the 
kernel memory allocation routines 


Syntax 

ccmn_get_dbuf(j/ze) 

u_long size; 


Arguments 

size Size of buffer in bytes. 

Description 

The ccmn_get_dbuf routine allocates a data buffer area of the size specified by 
calling the kernel memory allocation routines . 


Return Value 

Pointer to kernel data space. If this is NULL, no data buffer structures are available 
and no more can be allocated. 
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Name 


ccmn_init - initializes the XPT and the unit table lock structure 

Syntax 

ccmnjnit () 


Description 

The ccmn_init routine initializes the XPT and the unit table lock structure. The 
first time the ccmn_init routine is called, it calls the xpt_init routine to 
request the XPT to initialize the CAM subsystem. 

Return Value 

None 

See Also 

xpt_init 
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Name 


ccmn_io_ccb_bld - allocates a SCSI I/O CCB and fills it in 


Syntax 

ccmn_i0_ccb_bld(fitev, dataaddr, data_len, sense Jen, camJlags, comp June, \ 
tagaction, timeout, bp) 

dev_t dev; 
u_char * data addr; 
u_long datajen; 
u_short sense len; 
ujong camJlags; 
void ( *comp June) (); 
u_char tag action; 
u_long timeout; 
struct buf *bp; 


Arguments 


dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

data_addr Pointer to the data buffer. 

datajen Size of the data transfer. 

sense Jen Length of the sense data buffer to be returned on autosense, which is 
predefined as 64 bytes in the DEC_AUTO_SENSE_SIZE environment 
variable but can be larger. 

camJags The cam Jags flag names and their bit definitions are listed in the table 
that follows: 


Flag Name 


Description 


CAM_DIR_RESV 
CAM_DIR_IN 
CAM_DIR_OUT 
CAM_DIR_NONE 
CAM_DIS_AUTOS ENS E 
C AM_S CATTE R_VALID 
CAM_DIS_CALLBACK 
CAM_CDB_LINKED 
CAM_QUEUE_ENABLE 
CAM_CDB_POINTER 
CAM_DIS_DISCONNECT 
CAM INITIATE SYNC 


Data direction (00: reserved) 

Data direction (01: DATA IN) 
Data direction (10: DATA OUT) 
Data direction (11: no data) 

Disable autosense feature 
Scatter/gather list is valid 
Disable callback feature 
CCB contains linked CDB 
SIM queue actions are enabled 
CDB field contains pointer 
Disable disconnect 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 


SCSI/CAM Routines in ULTRIX Reference Page Format C-27 



Description 


Flag Name 

CAM_DIS_SYNC 

CAM_SIM_QHEAD 

CAM_SIM_QFREEZE 

CAM_ENG_SYNC 

CAM_ENG_SGLIST 

CAM_CDB_PHYS 

CAM_DATA_PHYS 

CAM_SNS_BUF_PHYS 

CAM_MSG_BUF_PHYS 

CAM_NXT_CCB_PHYS 

CAM_CALLBCK_PHYS 

CAM_DATAB_VALID 
CAM_STATUS_VALID 
CAM_MS GB_VALID 
CAM_TGT_PHASE_MODE 
CAM_TGT_CCB_AVAIL 
CAM_DIS_AUTODISC 
CAM DIS AUTOSRP 


Disable synchronous mode, go to 
asynchronous 

Place CCB at head of SIM queue 
Return SIM queue to frozen state 

Flush residual bytes from HBA 
data engine before terminating I/O 

Scatter/gather list is for HBA 
engine 

CDB pointer is physical address 

Scatter/gather/buffer data pointers 
are physical address 

Autosense data pointer is physical 
address 

Message buffer pointer is physical 
address 

Next CCB pointer is physical 
address 

Callback function pointer is 
physical address 

Data buffer valid 

Status buffer valid 

Message buffer valid 

SIM will run in phase mode 

Target CCB available 

Disable autodisconnect 

Disable autosave/restore pointers 


comp June SCSI device driver I/O callback completion function. This pointer may 
be NULL if the CAM DISABLE CALLBACK bit is set in the CAM 
FLAGS field. 

tag_action Type of action to perform for tagged requests: 

CAM_SIMPLE_QTAG Tag for simple queue 

CAM_H EAD_QTAG Tag for head of queue 

CAM_ORDERED_QTAG Tag for ordered queue 


timeout Timeout for the request in seconds. A value of 0 (zero) indicates the 
default, which is five seconds. 

bp A buf structure pointer, which is used for request mapping. This 

pointer may be NULL. 
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Description 

The ccmn_io_ccb_bld routine allocates a SCSI I/O CCB and fills it in. The 
routine calls the ccmn get ccb routine to obtain a CCB structure with the header 
portion filled in. The ccmn_io_ccb_bld routine fills in the SCSI I/O-specific 
fields from the parameters passed and checks the length of the sense data to see if it 
exceeds the length of the reserved sense buffer. If it does, a sense buffer is allocated 
using the ccmn_get_dbuf routine. 


Return Value 

Pointer to a SCSI I/O CCB 

See Also 

ccmn_get_ccb, ccmn_get_dbuf 
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Name 


ccmn_mode_select - creates a SCSI I/O CCB for the MODE SELECT command and 
sends it to the XPT for processing 

Syntax 

ccmn_mode_select(pd, sense Jen, cam Jags, comp June, tagaction, timeout, ms index) 

PDRVJDEVICE *pd\ 

u_short sense len; 

u_long camJlags; 

void ( *comp June ) (); 

u_char tagaction; 

ujong timeout; 

unsigned ms index ; 


Arguments 

pd Pointer to the CAM Peripheral Device Structure allocated for each SCSI 

device in the system. 

sense Jen Length of the sense data buffer to be returned on autosense, which is 
predefined as 64 bytes in the DEC_AUTO_SENSE_SIZE environment 
variable but can be larger. 

camJags The cam Jags flag names and their bit definitions are listed in the table 
that follows: 


Flag Name Description 


CAM_DIR_RESV 

CAM_DIR_IN 

CAM_DIR_OUT 

CAM_DIR_NONE 

CAM_DIS_AUTOS ENS E 

CAM_SCATTER_VALID 

CAM_DIS_CALLBACK 

CAM_CDB__LINKED 

CAM_QUEDE_ENABLE 

CAM_CDB_POINTER 

CAM_DIS_DISCONNECT 

CAM_INITIATE_SYNC 

CAM_DIS_SYNC 

CAM_SIM_QH EAD 
CAM SIM QFREEZE 


Data direction (00: reserved) 

Data direction (01: DATA IN) 
Data direction (10: DATA OUT) 
Data direction (11: no data) 

Disable autosense feature 
Scatter/gather list is valid 
Disable callback feature 
CCB contains linked CDB 
SIM queue actions are enabled 
CDB field contains pointer 
Disable disconnect 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 

Disable synchronous mode, go to 
asynchronous 

Place CCB at head of SIM queue 
Return SIM queue to frozen state 
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Flag Name 


Description 


CAM_ENG_SYNC 

Flush residual bytes from HBA 
data engine before terminating I/O 

CAM_ENG_SGLIST 

Scatter/gather list is for HBA 
engine 

CAM_CDB_PHYS 

CDB pointer is physical address 

CAM_DATA_P HY S 

Scatter/gather/buffer data pointers 
are physical address 

CAM_SNS_BUF_PHYS 

Autosense data pointer is physical 
address 

CAM_MSG_BUF_PHYS 

Message buffer pointer is physical 
address 

CAM_NXT_CCB_PHYS 

Next CCB pointer is physical 
address 

CAM_CALLBCK_PHYS 

Callback function pointer is 
physical address 

CAM_DATAB_VALID 

Data buffer valid 

CAM_STATUS_VALID 

Status buffer valid 

CAM_MSGB_VALID 

Message buffer valid 

CAM_TGT_PHAS E_MODE 

SIM will ran in phase mode 

CAM_TGT_CCB_AVAIL 

Target CCB available 

CAM_DIS_AUTODISC 

Disable autodisconnect 

CAM_DIS_AUTOSRP 

Disable autosave/restore pointers 


comp June SCSI device driver I/O callback completion function. This pointer may 
be NULL if the CAM DISABLE CALLBACK bit is set in the CAM 
FLAGS field. 

tag_action Type of action to perform for tagged requests: 

CAM_SIMPLE_QTAG Tag for simple queue 

CAM_head_qtag Tag for head of queue 

CAM_ORDERED_QTAG Tag for ordered queue 


timeout Timeout for the request in seconds. A value of 0 (zero) indicates the 
default, which is five seconds. 

msjndex An index into a page in the Mode Select Table that is pointed to in the 
Device Descriptor Structure. 

Description 

The ccmn_mode_select routine creates a SCSI I/O CCB for the MODE 
SELECT command and sends it to the XPT for processing. This routine may be 
called from interrupt context since it will not wait (sleep) for the command to 
complete. The routine calls the ccmn_io_ccb_bld routine to obtain a SCSI I/O 
CCB structure. It uses the msjndex parameter to index into the Mode Select Table 
pointed to by the dd_modsel_tbl member of the Device Descriptor Structure for 
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the SCSI device. The ccmn_mode_select routine calls the ccmn_send_ccb 
routine to send the SCSI I/O CCB to the XPT. 

Return Value 

CCB_SCSIIO pointer 

See Also 

ccmn_io_ccb_bld, ccmn_send_ccb 
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Name 


ccmn_open_unit - handles the common open for all SCSI/CAM peripheral device 
drivers 


Syntax 

ccmn_open_unit(dtfv, scsi_dev_type, flag, devjsize) 
dev_t dev; 

u_long scsi dev type; 
u_long flag; 
u_long devjsize; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

scsi_devjype 

SCSI device type value from Inquiry data. 

flag Indicates whether or not the device is being opened for exclusive use. A 

setting of 1 means exclusive use; a setting of 0 (zero) means 
nonexclusive use. 

devjsize The device-specific structure size in bytes. 


Description 

The ccmn_open_unit routine handles the common open for all SCSI/CAM 
peripheral device drivers. It must be called for each open before any SCSI device¬ 
specific open code is executed. 

On the first call to the ccmn_open_unit routine for a device, the 
ccmn_gdev_ccb_bld routine is called to issue a GET DEVICE TYPE CCB to 
obtain the Inquiry data. The ccmn_open_unit routine allocates the Peripheral 
Device Structure, PDRV_DEVICE, and a device-specific structure, either 
TAPE_SPECIFIC or DISK_SPECIFIC, based on the device size argument passed. 
The routine also searches the cam_devdesc_tab to obtain a pointer to the Device 
Descriptor Structure for the SCSI device and increments the open count. The 
statically allocated pdrv_unit_table structure contains a pointer to the 
PDRV_DEVICE structure. The PDRV_DEVICE structure contains pointers to the 
DEV_DESC structure and to the device-specific structure. 


Return Value 

The ccmn_open_unit routine returns a value of 0 (zero) upon successful 
completion. 
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Diagnostics 

The ccmn_open_unit routine fails under the following conditions: 

[EBUSY] The device is already opened and the exclusive use bit is set. 

[ENXIO] The device does not exist. 

[EINVAL] The scsidevjype parameter does not match the device type in the 
Inquiry data returned by GET DEVICE TYPE CCB. The 
scsi devjype was not configured. 


See Also 


ccmn_close_unit, ccmn_gdev_ccb_b 1 d 
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Name 


ccmn_pinq_ccb_bld - creates a PATH INQUIRY CCB and sends it to the XPT 


Syntax 

ccmn jDinq_ccb_bld ( dev, camJlags) 
dev_t dev; 
u_long camJlags; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

cam Jlags The cam Jlags flag names and their bit definitions are listed in the table 


that follows: 


Flag Name 

Description 

CAM_DIR_RESV 

Data direction (00: reserved) 

CAM_DIR_IN 

Data direction (01: DATA IN) 

CAM_DIR_OUT 

Data direction (10: DATA OUT) 

CAM_DIR_NONE 

Data direction (11: no data) 

CAM_DIS_AUTOS ENS E 

Disable autosense feature 

CAM_SCATTER_VALID 

Scatter/gather list is valid 

CAM_DIS_CALLBACK 

Disable callback feature 

CAM_CDB_LINKED 

CCB contains linked CDB 

CAM_QOEUE_ENABLE 

SIM queue actions are enabled 

CAM_CDB_POINTER 

CDB field contains pointer 

CAM_DIS_DISCONNECT 

Disable disconnect 

CAM_INITIATE_SYNC 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 

CAM_DIS_SYNC 

Disable synchronous mode, go to 
asynchronous 

CAM_SIM_QHEAD 

Place CCB at head of SIM queue 

CAM_SIM_QFREEZE 

Return SIM queue to frozen state 

CAM_ENG_SYNC 

Flush residual bytes from HBA 
data engine before terminating I/O 

CAM_ENG_SGLIST 

Scatter/gather list is for HBA 
engine 

CAM_CDB_PHYS 

CDB pointer is physical address 

CAM_DATA_PHYS 

Scatter/gather/buffer data pointers 
are physical address 

CAM_SNS_BUF_PHYS 

Autosense data pointer is physical 
address 
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Flag Name 

Description 

CAM_MSG_BUF_PHYS 

Message buffer pointer is physical 
address 

CAM_NXT_CCB_PHYS 

Next CCB pointer is physical 
address 

CAM_CALLBCK_PHYS 

Callback function pointer is 
physical address 

CAM_DATAB_VALID 

Data buffer valid 

CAM_STATUS_VALID 

Status buffer valid 

CAM_MS GB_VALID 

Message buffer valid 

CAM_TGT_PHASE_MODE 

SIM will run in phase mode 

CAM_TGT_CCB_AVAIL 

Target CCB available 

CAM_DIS_AUTODISC 

Disable autodisconnect 

CAM_DIS_AUTOSRP 

Disable autosave/restore pointers 


Description 

The ccmn_pinq_ccb_bld routine creates a PATH INQUIRY CCB and sends it 
to the XPT. The routine calls the ccmn_get_ccb routine to allocate a CCB 
structure and fill in the common portion of the CCB header. The routine calls the 
ccmn_send_ccb routine to send the CCB structure to the XPT. The request is 
carried out immediately, so it is not placed on the device driver’s active queue. 


Return Value 

CCB_PATHJNQ pointer 


See Also 

ccmn_get_ccb, ccmn_send_ccb 
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Name 


ccmn_rel_bp - deallocates a buf structure 


Syntax 

ccmn_rel_bp(fcp) 

struct buf *bp\ 


Arguments 

bp A buf structure pointer, which is used for request mapping. 

Description 

The ccmn_rel_bp routine deallocates a buf structure. 

Return Value 

None 
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Name 


ccmn_rel_ccb - releases a CCB and returns the sense data buffer for SCSI I/O CCBs, 
if allocated 


Syntax 

ccmn_rel_ccb(cd?) 

CCB.HEADER *ccb\ 


Arguments 

ccb Pointer to the CAM Control Block (CCB) header structure to be released. 


Description 

The ccmn_rel_ccb routine releases a CCB and returns the sense data buffer for 
SCSI I/O CCBs, if allocated. The routine calls the xpt_ccb_free routine to 
release a CCB structure. For SCSI I/O CCBs, if the sense data length is greater than 
the default sense data length, the ccmn_rel_ccb routine calls the 
ccmn_rel_dbuf routine to return the sense data buffer to the data buffer pool. 


Return Value 

None 

See Also 

ccmn_rel_dbuf, xpt_ccb_free 
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Name 


ccmn_rel_dbuf - deallocates a data buffer 


Syntax 

ccmn_rel_dbuf(flfiWr) 

caddr_t addr; 


Arguments 

addr Address of the data buffer to deallocate. 

Description 

The ccmn_rel_dbuf routine deallocates a data buffer. 

Return Value 

None 
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Name 


ccmn_rem_ccb - removes a SCSI I/O CCB request from the SCSI/CAM peripheral 
driver active queue and starts a tagged request if a tagged CCB is pending 

Syntax 

ccmn_rem_ccb {pd,ccb) 

PDRV_DEVICE *pd\ 

CCBJSCSIIO *ccb; 


Arguments 

pd Pointer to the CAM Peripheral Device Structure allocated for each SCSI 
device in the system. 

ccb Pointer to the SCSI I/O CCB structure to remove from the active queue. 

Description 

The ccmn_rem_ccb routine removes a SCSI I/O CCB request from the 
SCSI/CAM peripheral driver active queue and starts a tagged request if a tagged 
CCB is pending. If a tagged CCB is pending, the ccmn_rem_ccb routine places 
the request on the active queue and calls the xpt_action routine to start the 
tagged request. 

Return Value 

None 

See Also 

xpt_action 
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Name 


ccmn_rsq_ccb_bld - creates a RELEASE SIM QUEUE CCB and sends it to the XPT 


Syntax 

ccmn_rsq_ccb_bld ( dev, cam Jlags) 
dev_t dev; 
u_long cam Jlags; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

camJlags The cam Jags flag names and their bit definitions are listed in the table 


that follows: 

Flag Name 

Description 

CAM_DIR_RESV 

Data direction (00: reserved) 

CAM_DIR_IN 

Data direction (01: DATA IN) 

CAM_DIR_OUT 

Data direction (10: DATA OUT) 

CAM_DIR_NONE 

Data direction (11: no data) 

CAM_DIS_AUTOS ENSE 

Disable autosense feature 

CAM_SCATTER_VALID 

Scatter/gather list is valid 

CAM_DIS_CALLBACK 

Disable callback feature 

CAM_CDB_LINKED 

CCB contains linked CDB 

CAM_QUEUE_ENABLE 

SIM queue actions are enabled 

CAM_CDB_POINTER 

CDB field contains pointer 

CAM_DIS_DISCONNECT 

Disable disconnect 

CAM_INITIATE_SYNC 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 

CAM_DIS_SYNC 

Disable synchronous mode, go to 
asynchronous 

CAM_SIM_QHEAD 

Place CCB at head of SIM queue 

CAM_SIM_QFREEZE 

Return SIM queue to frozen state 

CAM_ENG_SYNC 

Rush residual bytes from HBA 
data engine before terminating I/O 

CAM_ENG_SGLIST 

Scatter/gather list is for HBA 
engine 

CAM_CDB_PHYS 

CDB pointer is physical address 

CAM_DATA_PHYS 

Scatter/gather/buffer data pointers 
are physical address 

CAM_SNS_BUF_PHYS 

Autosense data pointer is physical 
address 
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Flag Name 

Description 

CAM_MSG_BUF_PHYS 

Message buffer pointer is physical 
address 

CAM_NXT_CCB_PHYS 

Next CCB pointer is physical 
address 

CAM_CALLBCK_PHYS 

Callback function pointer is 
physical address 

CAM_DATAB_VALID 

Data buffer valid 

CAM_STATUS_VALID 

Status buffer valid 

CAM_MSGB_VALID 

Message buffer valid 

CAM_TGT_P HASE_MODE 

SIM will run in phase mode 

CAM_TGT_CCB_AVAIL 

Target CCB available 

CAM_DIS_AUTODISC 

Disable autodisconnect 

CAM_DIS_AUTOSRP 

Disable autosave/restore pointers 


Description 

The ccmn_rsq_ccb_bld routine creates a RELEASE SIM QUEUE CCB and 
sends it to the XPT. The routine calls the ccmn_get_ccb routine to allocate a 
CCB structure and fill in the common portion of the CCB header. The routine calls 
the ccmn_send_ccb routine to send the CCB structure to the XPT. The request is 
carried out immediately, so it is not placed on the device driver’s active queue. 


Return Value 

CCB_RELSIM pointer 


See Also 

ccmn_get_ccb, ccmn_send_ccb 
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Name 


ccmn_sasy_ccb_bld - creates a SET ASYNCHRONOUS CALLBACK CCB and 
sends it to the XPT 


Syntax 

ccmn_sasy_ccb_bld(dev, cam Jlags , asyncJiags , cal lbJune, buf, buflen) 

dev_t dev, 

u_long camJlags; 

u_long asyncJlags; 

void (flcallbJune) (); 

u_char *buf; 

u_char buflen; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

camJlags The cam Jlags flag names and their bit definitions are listed in the table 


that follows: 

Flag Name 

Description 

CAM_DIR_RESV 

Data direction (00: reserved) 

CAM_DIR_IN 

Data direction (01: DATA IN) 

CAM_DIR_OUT 

Data direction (10: DATA OUT) 

CAM_DIR_NONE 

Data direction (11: no data) 

CAM_DIS_AUTOS ENS E 

Disable autosense feature 

CAM_S CATTE R_VALID 

Scatter/gather list is valid 

CAM_DIS_CALLBACK 

Disable callback feature 

CAM_CDB_LINKED 

CCB contains linked CDB 

CAM_QUEUE_ENABLE 

SIM queue actions are enabled 

CAM_CDB_POINTER 

CDB field contains pointer 

CAM_DIS_DISCONNECT 

Disable disconnect 

CAM_INITIATE_SYNC 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 

CAM_DIS_SYNC 

Disable synchronous mode, go to 
asynchronous 

CAM_SIM_QHEAD 

Place CCB at head of SIM queue 

CAM_SIM_QFREEZE 

Return SIM queue to frozen state 

CAM_ENG_S YNC 

Flush residual bytes from HBA 
data engine before terminating I/O 

CAM_ENG_SGLIST 

Scatter/gather list is for HBA 
engine 
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Flag Name 

Description 

CAM_CDB_PHYS 

CDB pointer is physical address 

CAM_DATA_PHYS 

Scatter/gather/buffer data pointers 
are physical address 

CAM_SNS_BUF_PHYS 

Autosense data pointer is physical 
address 

CAM_MSG_BUF_PHYS 

Message buffer pointer is physical 
address 

CAM_NXT_CCB_PHYS 

Next CCB pointer is physical 
address 

CAM_CALLBCK_PHYS 

Callback function pointer is 
physical address 

CAM_DATAB_VALID 

Data buffer valid 

CAM_STATUS_VALID 

Status buffer valid 

CAM_MSGB_VALID 

Message buffer valid 

CAM_TGT_PHAS E_MODE 

SIM will run in phase mode 

CAM_TGT_CCB_AVAIL 

Target CCB available 

CAM_DIS_AUTODISC 

Disable autodisconnect 

CAM_DIS_AUTOSRP 

Disable autosave/restore pointers 


async JUigs Asynchronous Callback CCB flags for registering a callback routine for a 
specific bus, target, and LUN. The flags are defined in the 
/usr/sys/h/cam. h file. 

callb June Asynchronous callback function. 

buf SCSI/CAM peripheral buffer for asynchronous information. 

buflen Allocated SCSI/CAM peripheral buffer length. 


Description 

The ccmn_sasy_ccb_bld routine creates a SET ASYNCHRONOUS 
CALLBACK CCB and sends it to the XPT. The routine calls the ccmn_get_ccb 
routine to allocate a CCB structure and fill in the common portion of the CCB 
header. The routine fills in the asynchronous fields of the CCB and calls the 
ccmn_send_ccb routine to send the CCB structure to the XPT. The request is 
carried out immediately, so it is not placed on the device driver’s active queue. 


Return Value 

CCB_SETASYNC pointer 

See Also 

ccmn_get_ccb, ccmn_send_ccb 
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Name 


ccmn_sdev_ccb_bld - creates a SET DEVICE TYPE CCB and sends it to the XPT 

Syntax 

ccmn_sdev_ccb_bld(^v, camJlags , scsidevjype) 
dev_t dev, 
u_long cam Jlags ; 
u_char scsi_dev type ; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

camJlags The cam Jags flag names and their bit definitions are listed in the table 


that follows: 

Flag Name 

Description 

CAM_DIR_RESV 

Data direction (00: reserved) 

CAM_DIR_IN 

Data direction (01: DATA IN) 

CAM_DIR_OUT 

Data direction (10: DATA OUT) 

CAM_DIR_NONE 

Data direction (11: no data) 

CAM_DIS_AUTOS ENS E 

Disable autosense feature 

CAM_S CATT E R_VALID 

Scatter/gather list is valid 

CAM_DIS_CALLBACK 

Disable callback feature 

CAM_CDB_LINKED 

CCB contains linked CDB 

CAM_QUEUE_ENABLE 

SIM queue actions are enabled 

CAM_CDB_POINTER 

CDB field contains pointer 

CAM_DIS_DISCONNECT 

Disable disconnect 

CAM_INITIATE_SYNC 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 

CAM_DIS_SYNC 

Disable synchronous mode, go to 
asynchronous 

CAM_SIM_QHEAD 

Place CCB at head of SIM queue 

CAM_SIM_QFREEZE 

Return SIM queue to frozen state 

CAM_ENG_SYNC 

Hush residual bytes from HBA 
data engine before terminating I/O 

CAM_ENG_SGLIST 

Scatter/gather list is for HBA 
engine 

CAM_CDB_PHYS 

CDB pointer is physical address 

CAM_DATA_P HY S 

Scatter/gather/buffer data pointers 
are physical address 


SCSI/CAM Routines in ULTRIX Reference Page Format C-45 



Flag Name 


Description 


CAM_sns_buf_phys Autosense data pointer is physical 

address 

CAM_msg_buf_phys Message buffer pointer is physical 

address 

CAM_NXT_CCB_PHYS Next CCB pointer is physical 

address 

CAM_CALLBCK_PHYS Callback function pointer is 

physical address 

CAM_DATAB_VALID Data buffer valid 

CAM_STATUS_VALID Status buffer valid 

CAM_msgb_valid Message buffer valid 

Cam_tgt_PHAS E_MOD E SIM will run in phase mode 

CAM_TGT_CCB_AVAIL Target CCB available 

CAM_DIS_autodISC Disable autodisconnect 

CAM_DlS_AUTOSRP Disable autosave/restore pointers 

scsi_dev_type 

SCSI device type value from Inquiry data. 

Description 

The ccmn_sdev_ccb_bld routine creates a SET DEVICE TYPE CCB and sends 
it to the XPT. The routine calls the ccmn_get_ccb routine to allocate a CCB 
structure and fill in the common portion of the CCB header. The routine fills in the 
device type field of the CCB and calls the ccmn_send_ccb routine to send the 
CCB structure to the XPT. The request is carried out immediately, so it is not placed 
on the device driver’s active queue. 

Return Value 

CCBJSETDEV pointer 

See Also 

ccmn_get_ccb, ccmn_send_ccb 
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Name 


ccmn_send_ccb - sends CCBs to the XPT layer by calling the xpt_action 
routine 


Syntax 

ccmn_send_ccb(Mcc/?, retry) 
PDRV_DEVICE *pd\ 
CCB.HEADER *cd?; 
u_char retry 


Arguments 

pd Pointer to the CAM Peripheral Device Structure allocated for each SCSI 
device in the system. 

ccb Pointer to the CAM Control Block (CCB) header structure to be sent to the 
xpt_action routine to handle the request. 

retry Indicates whether this request is a retry of a request that is already on the 

active queue. A 1 indicates RETRY, and a 0 (zero) indicates NOT_RETRY. 

Description 

The ccmn_send_ccb routine sends CCBs to the XPT layer by calling the 
xpt_action routine. This routine must be called with the Peripheral Device 
Structure locked. 

For SCSI I/O CCBs that are not retries, the request is placed on the active queue. If 
the CCB is a tagged request and the tag queue size for the device has been reached, 
the request is placed on the tagged pending queue so that the request can be sent to 
the XPT at a later time. A high-water mark of half the queue depth for the SCSI 
device is used for tagged requests so that other initiators on the SCSI bus will not be 
blocked from using the device. 


Return Value 

Value returned from the xpt action routine. 

See Also 

xpt_action 
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Name 


ccmn_start_unit - creates a SCSI I/O CCB for the START UNIT command and 
sends it to the XPT for processing 


Syntax 

ccmn_start_unit(pd, sense Jen, cam Jlags, compJune , tagaction, timeout) 

PDRV_DEVICE *pd; 

u_short sense len; 

u_long camJlags; 

void (*comp June) (); 

u_char tag action; 

u_long timeout; 


Arguments 

pd Pointer to the CAM Peripheral Device Structure allocated for each SCSI 

device in the system. 

sense Jen Length of the sense data buffer to be returned on autosense, which is 
predefined as 64 bytes in the DEC_AUTO_SENSE_SIZE environment 
variable but can be larger. 

camJlags The cam Jlags flag names and their bit definitions are listed in the table 
that follows: 


Flag Name 


Description 


CAM_DIR_RESV 
CAM_DIR_IN 
CAM_DIR_OUT 
CAM_DIR_NONE 
CAM_DIS_AUTOSENSE 
CAM_SCATTER_VALID 
CAM_DIS_CALLBACK 
CAM_CDB_LINKED 
CAM_QUEUE_ENABLE 
CAM_CDB_POINTER 
CAM_DIS JDISCONNECT 
CAM_INITIATE_SYNC 

CAM_DIS_SYNC 

CAM_SIM_QHEAD 
CAM SIM QFREEZE 


Data direction (00: reserved) 

Data direction (01: DATA IN) 
Data direction (10: DATA OUT) 
Data direction (11: no data) 
Disable autosense feature 
Scatter/gather list is valid 
Disable callback feature 
CCB contains linked CDB 
SIM queue actions are enabled 
CDB field contains pointer 
Disable disconnect 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 

Disable synchronous mode, go to 
asynchronous 

Place CCB at head of SIM queue 
Return SIM queue to frozen state 
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Flag Name 

Description 

CAM_ENG_SYNC 

Flush residual bytes from HBA 
data engine before terminating I/O 

CAM_ENG_SGLIST 

Scatter/gather list is for HBA 
engine 

CAM_CDB_PHYS 

CDB pointer is physical address 

CAM_DATA_PHYS 

Scatter/gather/buffer data pointers 
are physical address 

CAM_SNS_BUF_PHYS 

Autosense data pointer is physical 
address 

CAM_MSG_BUF_PHYS 

Message buffer pointer is physical 
address 

CAM_NXT_CCB_P HYS 

Next CCB pointer is physical 
address 

CAM_CALLBCK_PHYS 

Callback function pointer is 
physical address 

CAM_DATAB_VALID 

Data buffer valid 

CAM_STATUS_VALID 

Status buffer valid 

CAM_MSGB_VALID 

Message buffer valid 

CAM_TGT_PHASE_MODE 

SIM will run in phase mode 

CAM_TGT_CCB_AVAIL 

Target CCB available 

CAM_DIS_AUTODISC 

Disable autodisconnect 

CAM_DIS_AUTOSRP 

Disable autosave/restore pointers 


comp June SCSI device driver I/O callback completion function. This pointer may 
be NULL if the CAM DISABLE CALLBACK bit is set in the CAM 
FLAGS field. 

tag_action Type of action to perform for tagged requests: 

CAM_SIMPLE_QTAG Tag for simple queue 

CAM HEAD QTAG Tag for head of queue 

CAM_ORDERED_QTAG Tag for ordered queue 


timeout Timeout for the request in seconds. A value of 0 (zero) indicates the 
default, which is five seconds. 


Description 

The ccmn_start_unit routine creates a SCSI I/O CCB for the START UNIT 
command and sends it to the XPT for processing. This routine may be called from 
interrupt context since it will not wait (sleep) for the command to complete. 

The ccmn_start_unit routine calls the ccmn_io_ccb_bld routine to obtain 
a SCSI I/O CCB structure. The ccmn_start_unit routine calls the 
ccmn send ccb routine to send the SCSI I/O CCB to the XPT. 
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Return Value 

CCB_SCSIIO pointer 

See Also 

ccmn_io_ccb bid, ccmn_send ccb 
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Name 


ccmn_term_ccb_bld - creates a TERMINATE I/O CCB and sends it to the XPT 


Syntax 

ccmn_term_ccb_bld(^v, camJlags , term_ccb) 
dev_t dev; 
u_long camJlags ; 

CCB_HEADER *term_ccb; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

cam Jlags The cam Jlags flag names and their bit definitions are listed in the table 
that follows: 


Flag Name 

Description 

CAM_DIR_RESV 

Data direction (00: reserved) 

CAM_DIR_IN 

Data direction (01: DATA IN) 

CAM_DIR_OUT 

Data direction (10: DATA OUT) 

CAM_DIR_NONE 

Data direction (11: no data) 

CAM_DIS_AUTOS ENS E 

Disable autosense feature 

CAM_SCATTER_VALID 

Scatter/gather list is valid 

CAM_DIS_CALLBACK 

Disable callback feature 

CAM_CDB_LINKED 

CCB contains linked CDB 

CAM__QUEUE_ENABLE 

SIM queue actions are enabled 

CAM_CDB_POINTER 

CDB field contains pointer 

CAM_DIS_DISCONNECT 

Disable disconnect 

CAM_INITIATE_SYNC 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 

CAM_DIS_SYNC 

Disable synchronous mode, go to 
asynchronous 

CAM_SIM_QHEAD 

Place CCB at head of SIM queue 

CAM_SIM_QFREEZE 

Return SIM queue to frozen state 

CAM_ENG_SYNC 

Flush residual bytes from HBA 
data engine before terminating I/O 

CAM_ENG_SGLIST 

Scatter/gather list is for HBA 
engine 

CAM_CDB_PHYS 

CDB pointer is physical address 

CAM_DATA_PHYS 

Scatter/gather/buffer data pointers 
are physical address 
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Flag Name 

Description 

CAM_SNS_BUF_PHYS 

Autosense data pointer is physical 
address 

CAM_MSG_BUF_PHYS 

Message buffer pointer is physical 
address 

CAM_NXT_CCB_PHYS 

Next CCB pointer is physical 
address 

CAM_CALLBCK_PHYS 

Callback function pointer is 
physical address 

CAM_DATAB_VALID 

Data buffer valid 

CAM_STATUS_VALID 

Status buffer valid 

CAM_MSGB_VALID 

Message buffer valid 

CAM_TGT_PHAS E_MODE 

SIM will run in phase mode 

CAM_TGT_CCB_AVAIL 

Target CCB available 

CAM_DIS_AUTODISC 

Disable autodisconnect 

CAM_DIS_AUTOSRP 

Disable autosave/restore pointers 


termjccb Pointer to the CAM Control Block (CCB) header structure to terminate. 

Description 

The ccmn_term_ccb_bld routine creates a TERMINATE I/O CCB and sends it 
to the XPT. The routine calls the ccmn_get_ccb routine to allocate a CCB 
structure and fill in the common portion of the CCB header. The routine fills in the 
CCB to be terminated and calls the ccmn_send_ccb routine to send the CCB 
structure to the XPT. The request is carried out immediately, so it is not placed on 
the device driver’s active queue. 


Return Value 

CCB_TERMIO pointer 


See Also 


ccmn_get_ccb, ccmn_send_ccb 
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Name 


ccmn_term_que - sends a TERMINATE I/O CCB request for each SCSI I/O CCB on 
the active queue 


Syntax 

ccmn_term_que(pd) 

PDRV.DEVICE *pd\ 


Arguments 

pd Pointer to the CAM Peripheral Device Structure allocated for each SCSI 
device in the system. 

Description 

The ccmn_term_que routine sends a TERMINATE I/O CCB request for each 
SCSI I/O CCB on the active queue. This routine must be called with the Peripheral 
Device Structure locked. 

The ccmn_term_que routine calls the ccmn_term_ccb_bld routine to create 
a TERMINATE I/O CCB for the first active CCB on the active queue and send it to 
the XPT. It calls the ccmn_send_ccb routine to send the TERMINATE I/O CCB 
for each of the other CCBs on the active queue that are marked as active to the XPT. 
The ccmn_term_que routine then calls the ccmn_rel_ccb routine to return 
the TERMINATE I/O CCB to the XPT. 


Return Value 

None 


See Also 

ccmn_rel_ccb, ccmn_send ccb 
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Name 


ccmn_tur - creates a SCSI I/O CCB for the TEST UNIT READY command and 
sends it to the XPT for processing 


Syntax 

ccmn_tur(pd, sense len, camJlags, compJune, tag action, timeout ) 

PDRV_DEVICE *pd\ 

u_short sense Jen; 

ujong camJlags-, 

void ( *compJune) (); 

u_char tag_action; 

ujong timeout; 


Arguments 


pd Pointer to the CAM Peripheral Device Structure allocated for each SCSI 

device in the system. 

sense Jen Length of the sense data buffer to be returned on autosense, which is 
predefined as 64 bytes in the DEC_AUTO_SENSE_SIZE environment 
variable but can be larger. 

camJlags The cam Jlags flag names and their bit definitions are listed in the table 
that follows: 


Flag Name Description 


CAM_DIR_RESV 
CAM_DIR_IN 
CAM_DIR_OUT 
CAM_DIR_NONE 
CAM_DIS_AUTOS ENS E 
CAM_S CATT E R_VALID 
CAM_DIS_CALLBACK 
CAM_CDB_LINKED 
CAM_QUEUE_ENABLE 
CAM_CDB_POINTER 
CAM__DIS_DISCONNECT 
CAM_INITIATE_SYNC 

CAM_DIS_SYNC 

CAM_SIM_QHEAD 
CAM SIM QFREEZE 


Data direction (00: reserved) 

Data direction (01: DATA IN) 
Data direction (10: DATA OUT) 
Data direction (11: no data) 
Disable autosense feature 
Scatter/gather list is valid 
Disable callback feature 
CCB contains linked CDB 
SIM queue actions are enabled 
CDB field contains pointer 
Disable disconnect 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 

Disable synchronous mode, go to 
asynchronous 

Place CCB at head of SIM queue 
Return SIM queue to frozen state 
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Flag Name 

Description 

CAM_ENG_SYNC 

Flush residual bytes from HBA 
data engine before terminating I/O 

CAM_ENG_SGLIST 

Scatter/gather list is for HBA 
engine 

CAM_CDB_P HY S 

CDB pointer is physical address 

CAM_DATA_PHYS 

Scatter/gather/buffer data pointers 
are physical address 

CAM_SNS_BUF_PHY S 

Autosense data pointer is physical 
address 

CAM_MSG_BUF_PHYS 

Message buffer pointer is physical 
address 

CAM_NXT_CCB_PHYS 

Next CCB pointer is physical 
address 

CAM_CALLBCK_PHYS 

Callback function pointer is 
physical address 

CAM_DATAB_VALID 

Data buffer valid 

CAM_STATUS_VALID 

Status buffer valid 

CAM_MSGB__VALID 

Message buffer valid 

CAM_TGT_PHAS EJMODE 

SIM will run in phase mode 

CAM_TGT_CCB_AVAIL 

Target CCB available 

CAM_DIS_AUTODISC 

Disable autodisconnect 

CAM_DIS_AUTOSRP 

Disable autosave/restore pointers 


comp June SCSI device driver I/O callback completion function. This pointer may 
be NULL if the CAM DISABLE CALLBACK bit is set in the CAM 
FLAGS field. 

tag_action Type of action to perform for tagged requests: 

CAM_SIMPLE_QTAG Tag for simple queue 

CAM_head_QTAG Tag for head of queue 

CAM_ORDERED_QTAG Tag for ordered queue 


timeout Timeout for the request in seconds. A value of 0 (zero) indicates the 
default, which is five seconds. 


Description 

The ccmn_tur routine creates a SCSI I/O CCB for the TEST UNIT READY 
command and sends it to the XPT for processing. This routine may be called from 
interrupt context since it will not wait (sleep) for the command to complete. 

The ccmn_tur routine calls the ccmn_io_ccb_bld routine to obtain a SCSI 
I/O CCB structure. The ccmn_tur routine calls the ccmn_send_ccb routine to 
send the SCSI I/O CCB to the XPT. 
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Return Value 

CCB_SCSIIO pointer 

See Also 

ccmn io ccb bid, ccmn send ccb 
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Name 


cdbg_CamFunction - reports CAM XPT function codes 

Syntax 

char * cdbg_CamFunction {camJunction, report Jormat ) 
register u_char cam Junction ; 
int reportJormat ; 


Arguments 

cam Junction The entry from the CAM XPT Function Code Table. 

reportjormat The format of the message text returned, which can be CDBG_BRIEF 
or CDBG_FULL. 

Description 

The cdbg_CamFunction routine reports CAM XPT function codes. Program 
constants are defined to allow either the function code name only or a brief 
explanation to be printed. The XPT function codes are defined in the 
/usr/sys/h/cam.h file. 

Return Value 

Returns a character pointer to a text string. 
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Name 


cdbg_CamStatus - decodes CAM CCB status codes 

Syntax 

char * ctibg_CamS\a\us(cam_status, report Jormat) 
register u_char cam status', 
int reportJormat ; 

Arguments 

cam jtatus The information from the CAM SCSI I/O CCB. 

report Jormat The format of the message text returned, which can be CDBGJBRIEF 
or CDBG_FULL. 

Description 

The cdbg_CamStatus routine decodes CAM CCB status codes. Program 
constants are defined to allow either the status code name only or a brief explanation 
to be printed. The CAM status codes are defined in the /usr/sys/h/cam. h file. 

Return Value 

Returns a character pointer to a text string. 
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Name 


cdbg_DumpABORT - dumps the contents of an ABORT CCB 


Syntax 

void cdbg_DumpABORT(cc&) 
register CCB_ABORT *ccb\ 


Arguments 

ccb Pointer to the ABORT CCB. 


Description 

The cdbg DumpABORT routine dumps the contents of an ABORT CCB. The 
ABORT CCB is defined in the /usr/sys/h/cam. h file. 


Return Value 

None 
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Name 


void cdbg_DumpBuffer - dumps the contents of a data buffer in hexadecimal bytes 


Syntax 

void cdbg_DumpBuffer(2?wjf<?r, size) 
char * buffer, 

register int size; 


Arguments 

buffer SCSI/CAM peripheral buffer pointer. 
size Size of buffer in bytes. 

Description 

The cdbg_DumpBuf f er routine dumps the contents of a data buffer in 
hexadecimal bytes. The calling routine must display a header line. The format of the 
dump is 16 bytes per line. 

Return Value 

None 
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Name 


cdbg_DumpCCBHeader - dumps the contents of a CAM Control Block (CCB) 
header structure 


Syntax 

void cdbg_DumpCCBHeader(cc&) 

register CCBJHDEADER *ccb; 


Arguments 

ccb Pointer to the CAM Control Block (CCB) header structure. 


Description 

The cdbg_DumpCCBHeader routine dumps the contents of a CAM Control Block 
(CCB) header structure. The CAM Control Block (CCB) header structure is defined 
in the /usr/sys/h/cam . h file. 


Return Value 

None 
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Name 


cdbg_DumpCCBHeaderFlags - dumps the contents of the cam_f lags member of 
a CAM Control Block (CCB) header structure 


Syntax 

void cdbg_DumpCCBHeaderFiags(cam Jlags) 
register u_long cam Jlags; 

Arguments 

camJlags The cam Jags flag names and their bit definitions are listed in the table 
that follows: 


Flag Name 

Description 

CAM_DIR_RESV 

Data direction (00: reserved) 

CAM_DIR_IN 

Data direction (01: DATA IN) 

CAM_DIR_OUT 

Data direction (10: DATA OUT) 

CAM_DIR_NONE 

Data direction (11: no data) 

CAM_DIS_AUTOSENS E 

Disable autosense feature 

CAM_SCATTER_VALID 

Scatter/gather list is valid 

CAM_DIS_CALLBACK 

Disable callback feature 

CAM_CDB_LINKED 

CCB contains linked CDB 

CAM_QUEUE_ENABLE 

SIM queue actions are enabled 

CAM_CDB_POINTER 

CDB field contains pointer 

CAM_DIS_DISCONNECT 

Disable disconnect 

CAM_INITIATE_SYNC 

Attempt synchronous data transfer, 
after issuing Synchronous Data 
Transfer Request (SDTR) 

CAM_DIS_SYNC 

Disable synchronous mode, go to 
asynchronous 

CAM_SIM_QHEAD 

Place CCB at head of SIM queue 

CAM_SIM_QFREEZE 

Return SIM queue to frozen state 

CAM_ENG_SYNC 

Flush residual bytes from HBA 
data engine before terminating I/O 

CAM_ENG_SGLIST 

Scatter/gather list is for HBA 
engine 

CAM_CDB_PHY S 

CDB pointer is physical address 

CAM_DATA_PHYS 

Scatter/gather/buffer data pointers 
are physical address 

CAM_SNS_BUF_PHYS 

Autosense data pointer is physical 
address 

CAM_MSG_BUF_PHYS 

Message buffer pointer is physical 
address 
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Flag Name 

Description 

CAM_NXT_CCB_PHYS 

Next CCB pointer is physical 
address 

CAM_CALLBCK_PHY S 

Callback function pointer is 
physical address 

CAM_DATAB_VALID 

Data buffer valid 

CAM_STATUS_VALID 

Status buffer valid 

CAM_MS GB__VAL ID 

Message buffer valid 

CAM_TGT_PHAS E_MODE 

SIM will run in phase mode 

CAM_TGT_CCB_AVAIL 

Target CCB available 

CAM_DIS_AUTODISC 

Disable autodisconnect 

CAM_DIS_AUTOSRP 

Disable autosave/restore pointers 


Description 

The cdbg_DumpCCBHeaderFlags routine dumps the contents of the 
cam_f lags member of a CAM Control Block (CCB) header structure. The CAM 
Control Block (CCB) header structure is defined in the /usr/sys/h/cam . h file. 

Return Value 

None 
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Name 


cdbg_DumpInquiryData - dumps the contents of an ALL_INQ_DATA structure 


Syntax 

void cdbg_DumplnquiryData(m^«/ry) 

register ALL_INQ_DATA * inquiry ; 


Arguments 

inquiry Pointer to the ALL_INQ_DATA structure. 

Description 

The cdbg_DumpInquiryData routine dumps the contents of an 
ALL_INQ_DATA structure. The ALL_INQ_DATA structure is defined in the 
/usr/sys/h/scsi_all. h file. 

Return Value 

None 
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Name 


cdbg_DumpPDRVws - dumps the contents of a SCSI/CAM Peripheral Device Driver 
Working Set Structure 


Syntax 

void cdbg_DumpPDRVws(/wtf) 

register PDRV_WS *pws; 


Arguments 

pws Pointer to the SCSI/CAM Peripheral Device Driver Working Set Structure. 


Description 

The cdbg_DumpPDRVws routine dumps the contents of a SCSI/CAM Peripheral 
Device Driver Working Set Structure. The SCSI/CAM Peripheral Device Driver 
Working Set Structure is defined in the /usr/sys/h/pdrv . h file. 


Return Value 

None 
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Name 


cdbg_DumpSCSIIO - dumps the contents of a SCSI I/O CCB 


Syntax 

void cdbg_DumpSCSIIO(cd>) 

register CCB_SCSIIO *ccb\ 


Arguments 

ccb Pointer to the SCSI I/O CCB structure. 


Description 

The cdbg_DumpSCSHO routine dumps the contents of a SCSI I/O CCB. The 
SCSI I/O CCB is defined in the /usr/sys/h/cam. h file. 


Return Value 

None 
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cdbg_DumpTERMIO - dumps the contents of a TERMINATE I/O CCB 


Syntax 

void cdbg_DumpTERMIO {ccb) 
register CCB_TERMIO *ccb\ 


Arguments 

ccb Pointer to the TERMINATE I/O CCB. 


Description 

The cdbg DumpTERMlO routine dumps the contents of a TERMINATE I/O CCB. 
The TERMINATE I/O CCB is defined in the /usr/sys/h/cam. h file. 


Return Value 

None 
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Name 


cdbg_GetDeviceName - returns a pointer to a character string describing the dtype 
member of an ALL_INQ_DATA structure 


Syntax 

char * c6bg_Ge\DeV\ce^ame{devicetype) 
register device jype ; 


Arguments 

device Jype SCSI device type value from Inquiry data. 


Description 

The cdbg_GetDeviceName routine returns a pointer to a character string 
describing the dtype member of an ALL_INQ_DATA structure. The 
ALL_INQ_DATA structure is defined in the /usr/sys/h/scsi_all. h file. 

Return Value 

Returns a character pointer to a text string. 
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Name 


cdbg_ScsiStatus - reports SCSI status codes 


Syntax 

char * c6bQ_Scs\S\a\us{scsi_status, report Jormat) 
register u_char scsi_status; 
int reportJormat; 


Arguments 

scsi_status The SCSI status from the CAM SCSI I/O CCB. 
reportJormat 

The format of the message text returned, which can be CDBG_BRIEF or 
CDBG_FULL. 

Description 

The cdbg_ScsiStatus routine reports SCSI status codes. Program constants are 
defined to allow either the status code name only or a brief explanation to be printed. 
The SCSI status codes are defined in the /usr/sys/h/scsi_status . h file. 

Return Value 

Returns a character pointer to a text string. 
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Name 


cdbg_SystemStatus - reports system error codes 


Syntax 

char * cdbg_SystemStatus(errn<9) 

int ermo\ 


Arguments 

errno The error number. 

Description 

The cdbg_SystemStatus routine reports system error codes. The system error codes 
are defined in the /usr/sys/h/errno. h file. 

Return Value 

Returns a character pointer to a text string. 
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cgen_async - handles notification of asynchronous events 


Syntax 

void cgen_async{opcode, pathjd, target , lun, buf_ptr, datajent ) 

u_long opcode; 

u_char pathjd; 

u_char target; 

u_char lun; 

caddr_t buf_ptr; 

u_char data cnt; 


Arguments 

opcode SCSI asynchronous callback operation code. 
pathjd SCSI target’s bus controller number. 
target SCSI target’s ID number. 

lun SCSI target’s logical unit number. 

buf_ptr Buffer address for Asynchronous Event Notification (AEN). 

data_cnt Number of bytes the XPT had to transfer from the SIM’s buffer or the 
limit of the SCSI/CAM peripheral buffer. 

Description 

The cgen_async routine handles notification of asynchronous events. The routine 
is called when an Asynchronous Event Notification(AEN), Bus Device Reset (BDR), 
or Bus Reset (BR) occurs. The routine sets the CGENJRESETJSTATE flag and 
clears the CGEN_RESET_PEND_STATE flag for BDRs and bus resets. The routine 
sets the CGEN_UNIT_ATTEN_STATE flag for AENs. 

Return Value 

None 
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Name 


cgen_attach - called for each bus, target, and LUN after the cgen_slave routine 
returns SUCCESS 


Syntax 

cgen_attach(iu) 

struct uba_device *ui\ 


Arguments 

ui Pointer to the device information contained in the uba_devi.ce 

structure. 


Description 

The cgen_attach routine is called for each bus, target, and LUN after the 
cgen_slave routine returns SUCCESS. The routine calls the 
ccmn_open_unit routine, passing the bus, target, and LUN information. 

The cgen_attach routine calls the ccmn_close_unit routine to close the 
device. If a device of the specified type is found, the device identification string is 
printed. See the Guide to Writing and Porting VMEbus and TURBOchannel Device 
Drivers for more information. 


Return Value 

PROBE_FAILURE 

PROBESECCESS 


See Also 

ccmn_close_unit, ccmn_open_unit, cgen_slave 
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Name 


cgen_ccb_chkcond - decodes the autosense data for a device driver 


Syntax 

cgen_ccb_chkcond(/?drv_dev, ccb) 
PDRV_DEVICE *pdrv_dev ; 
CCB_SCSIIO *ccb; 


Arguments 

pdrv_dev Pointer to the CAM Peripheral Device Structure allocated for each SCSI 
device in the system. 

ccb Pointer to the SCSI I/O CCB structure. 

Description 

The cgen_ccb_chkcond routine decodes the autosense data for a device driver 
and returns the appropriate status to the calling routine. The routine is called when a 
SCSI I/O CCB is returned with a CAM status of CAM_REQ_CMP_ERR (request 
completed with error) and a SCSI status of SCSI_STAT_CHECK_CONDITION. The 
routine also sets the appropriate flags in the Generic-Specific Structure. 


Return Value 

An integer indicating one of the following values: 

Flag Name Description 

CHK_CHK_NOSENSE Request sense did not complete 

without error. Sense buffer 
contents cannot be used to 
determine error condition. 


CHK_SENSE_NOT_VALID 

CHK_EOM 

CHK_FILEMARK 

CHK_ILI 

CHK_NOSENSE_BITS 

CHK_SOFTERR 

CHK_NOT_READY 
CHK_HARDERR 
CHK UNIT ATTEN 


Valid bit in sense buffer is not set; 
sense data is useless. 

End of media detected. 

Filemaric detected. 

Incorrect record length detected. 

Sense key equals no sense, but 
there are no bits set in byte 2 of 
sense data. 

Soft error detected; corrected by 
unit. 

Unit is not ready. 

Unit has detected a hard error. 

Unit has either had media change 
or just powered up. 
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Flag Name 

Description 

CHK_DATA_PROT 

Unit is write protected. 

CHK_UNSUPPORTED 

Sense key that is unsupported has 
been returned. 

CHK_CMD_ABORTED 

Unit aborted this command. 

CHK_INFORMATIONAL 

Unit is reporting informational 
message. 

CHK_UNKNOWN_KEY 

Unit has returned sense key that is 
not supported by SCSI 2 
specification. 
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Name 


cgen_close - closes the device 

Syntax 

cgen_close(<fev, flags) 
dev_t dev; 
int flags; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

flags Flags set when a file is open. 


Description 

The cgen_close routine closes the device. The routine checks any device flags 
that are defined to see if action is required, such as rewind on close or release the 
unit. The cgen_close closes the device by calling the ccmn_close_unit 
routine. 


Return Value 

The cgen_close routine returns GENERIC_SUCCESS upon successful 
completion. 


Diagnostics 

The cgen_close routine fails under the following condition: 
[ENOMEM] Resource problem 

See Also 

ccmn close unit 
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Name 


cgen_done - the entry point for all nonread and nonwrite I/O callbacks 


Syntax 

cgen_done(cd>) 

CCBJSCSIIO *ccb\ 


Arguments 

ccb Pointer to the SCSI I/O CCB structure. 


Description 

The cgen_done routine is the the entry point for all nonread and nonwrite I/O 
callbacks. The generic device driver uses two callback entry points, one for all 
nonuser I/O requests and one for all user I/O requests. The SCSI/CAM peripheral 
device driver writer can declare multiple callback routines for each type of command 
and can fill the CCB with the address of the appropriate callback routine. 

This is a generic routine for all nonread and nonwrite SCSI I/O CCBs. The SCSI I/O 
CCB should not contain a pointer to a buf structure in the cam_req_map 
member of the structure. If it does, then a wake-up call is issued on the address of 
the CCB and the error is reported. If the SCSI I/O CCB does not contain a pointer to 
a buf structure in the cam_req_map member, then a wake-up call is issued on 
the address of the CCB and the CCB is removed from the active queques. No CCB 
completion status is checked because that is the responsibility of the routine that 
created the CCB and is waiting for completion status. When this routine is entered, 
context is on the interrupt stack and the driver cannot sleep waiting for an event. 


Return Value 

None 
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Name 


cgenjoctl - handles user process requests for specific actions other than read, write, 
open, or close for SCSI tape devices 


Syntax 

cgenjoctl (dev, cmd, data, flags) 

dev_t dev; 

int cmd\ 

caddt_t data; 

int flags; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

cmd The ioctl command, UAGT_CAM_IO. 

data Pointer to the kernel copy of the structure passed by the user process. 
flags User process flags. 


Description 

The cgen_ioctl routine handles user process requests for specific actions other 
than read, write, open, or close for SCSI tape devices. The routine currently issues a 
DEVIOCGET ioctl command for the device, which fills out the devget 
structure passed in, and then calls the cgen_mode_sns routine which issues a 
SCSI_MODE_SENSE to the device to determine the device’s state. The routine then 
calls the ccmn_rel_ccb routine to release the CCB. When the call to 
cgen_mode_sns completes, the cgen_ioctl routine fills out the rest of the 
devget structure based on information contained in the mode sense data. 


Return Value 

[EINVAL] The device does not exist. 

See Also 

ccmn__rel_ccb , cgen_mode_sns , ioctl(2) 
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Name 


cgen_iodone - the entry point for all read and write I/O callbacks 


Syntax 

cgenJodone(cd>) 

CCB_SCSIIO *ccb; 


Arguments 

ccb Pointer to the SCSI I/O CCB structure. 


Description 

The cgen_iodone routine is the entry point for all read and write I/O callbacks. 
This is a generic routine for all read and write SCSI I/O CCBs. The SCSI I/O CCB 
should contain a pointer to a buf structure in the cam_req_map member of the 
structure. If it does not, then a wake-up call is issued on the address of the CCB and 
the error is reported. If the SCSI I/O CCB does contain a pointer to a buf structure 
in the cam_req_map member, as it should, then the completion status is decoded. 
Depending on the CCB’s completion status, the correct fields within the buf 
structure are filled out. 

The device’s active queues may need to be aborted because of errors or because the 
device is a sequential access device and the transaction was an asynchronous request. 

The CCB is removed from the active queques by a call to the ccmn_rem_ccb 
routine and is released back to the free CCB pool by a call to the ccmn_rel_ccb 
routine. When the cgen_iodone routine is entered, context is on the interrupt 
stack and the driver cannot sleep waiting for an event. 


Return Value 

None 

See Also 

ccmn_rem_ccb , ccmn_rel_ccb 
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Name 


cgen_minphys - compares the bjbcount with the maximum transfer limit for the 
device 


Syntax 

cgen_minphys(fcp) 

register struct buf *bp\ 


Arguments 

bp A buf structure pointer, which is used for request mapping. 


Description 

The cgen_minphys routine compares the b_bcount with the maximum transfer 
limit for the device. The routine compares the b_bcount field in the buf 
structure with the maximum transfer limit for the device in the Device Descriptor 
Structure. The count is adjusted if it is greater than the limit. 

Return Value 

None 
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Name 


cgen_mode_sns - issues a SCSI_MODE_SENSE command to the unit defined 


Syntax 

cgen_mode_sns(pdrv dev, action, done, pagejcode, page_ctrl, sleep ) 
PDRV_DEVICE *pdrv_dev; 

CGEN_ACTION * action , 
void ( *done ) (); 
u_char page_code; 
u_char page_ctrl; 
u_long sleep; 


Arguments 


pdrvdev 

action 

done 

pagejcode 

pagejctrl 

sleep 


Pointer to the CAM Peripheral Device Structure allocated for each SCSI 
device in the system. 

Pointer to the caller’s Generic Action Structure. 

The address of the completion routine to be called when the SCSI 
command completes. 

The user process’s target page. 

The page control settings field. 

Whether or not the GENERIC_SLEEP flag is set. 


Description 

The cgen mode sns routine issues a SCSI_MODE_SENSE command to the unit 
defined. The CGEN_ACTION structure is filled in for the calling routine based on 
the completion status of the CCB. 


Return Value 

NULL - command could not be issued 
CCB_SCSIIO pointer 


See Also 

ccmn ccb status 
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Name 


cgen_open - called by the kernel when a user process requests an open of the device 


Syntax 

cgen_open(<fev, flags) 
dev_t dev; 
int flags; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

flags Flags set when a file is open. 


Description 

The cgen_open routine is called by the kernel when a user process requests an 
open of the device. The cgen_open routine calls the ccmn_open_unit 
routine, which manages the SMP_LOCKS and, if passed the exclusive use flag for 
SCSI devices, makes sure that no other process has opened the device. If the 
ccmn_open_unit routine returns success, the necessary data structures are 
allocated. 

The cgen_open routine calls the ccmn_sasy_ccb_bld routine to register for 
asynchronous event notification for the device. The cgen_open routine then enters 
a for loop based on the power-up time specified in the Device Descriptor Structure 
for the device. Within the loop, calls are made to the cgen_ready routine, which 
calls the ccmn_tur routine to issue a TEST UNIT READY command to the 
device. 

The cgen_open routine calls the ccmn_rel_ccb routine to release the CCB. 
The cgen_open routine checks certain state flags for the device to decide whether 
to send the initial SCSI mode select pages to the device. Depending on the setting of 
the state flags CGEN_UNIT_ATTEN_STATE and CGEN_RESET_STATE, the 
cgen_open routine calls the cgen_open_sel routine for each mode select page 
to be sent to the device. The cgen_open_sel routine fills out the Generic Action 
Structure based on the completion status of the CCB for each mode select page it 
sends. 


Return Value 

The cgen open routine returns GENERIC_SUCCESS upon successful 
completion. 


Diagnostics 

The cgen_open routine fails under the following conditions: 
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[EBUSY] 

The device is already opened and the exclusive use bit is set. 

[ENOMEM] 

Resource problem 

[EINVAL] 

The scsi_dev_type parameter does not match the device type in 
Inquiry data returned by GET DEVICE TYPE CCB. The 
scsi_dev_type was not configured. 

[ENXIO] 

The device does not exist. 

[EIO] 

Check device conditions. 


See Also 

ccmn_close_unit, ccmn_open_unit, ccmn__rel_ccb , 
ccmn_sasy_ccb_bld , ccmn_tur , cgen_open_sel , cgen_close 
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Name 


cgen_open_sel - issues a SCSI_MODE_SELECT command to the SCSI device 


Syntax 

cgen_open_sel(pdrv_dev, action, msjndex, done, sleep ) 
PDRV_DEVICE *pdrv_dev ; 

CGEN.ACTION *action; 
u_long ms index-, 
void (*done) (); 
u_long sleep ; 


Arguments 


pdrv_dev Pointer to the CAM Peripheral Device Structure allocated for each SCSI 
device in the system. 

action Pointer to the caller’s Generic Action Structure. 

msjndex An index into a page in the Mode Select Table that is pointed to in the 
Device Descriptor Structure. 

done The address of the completion routine to be called when the SCSI 
command completes. 

sleep Whether or not the GENERIC_SLEEP flag is set. 

Description 

The cgen_open_sel routine issues a SCSI_MODE_SELECT command to the 
SCSI device. The mode select data sent to the device is based on the data contained 
in the Mode Select Table Structure for the device, if one is defined. The 
CGEN_ACTION structure is filled in for the calling routine based on the completion 
status of the CCB. 

The cgen_open_sel routine calls the ccmn_mode_select routine to create a 
SCSI I/O CCB and send it to the XPT for processing. 


Return Value 

None 


See Also 

ccmn ccb_status , ccmn mode_select 
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Name 


cgen_read - handles synchronous read requests for user processes 

Syntax 

cgen_read(dev, uio) 
dev_t dev\ 
struct uio *uio\ 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

uio Pointer to the device information contained in the uio I/O structure. 


Description 

The cgen_read routine handles synchronous read requests for user processes. It 
passes the user process requests to the cgen_strategy routine. The 
cgen_read routine calls the ccmn_get_bp routine to allocate a buf structure 
for the user process read request. When the I/O is complete, the cgen_read 
routine calls the ccmn_rel_bp routine to deallocate the buf structure. 

Return Value 

The cgen_read routine passes the return from the physio routine. 

See Also 

ccmn_get_bp , ccmn_rel_bp , cgen_strategy 
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Name 


cgen_ready - issues a TEST UNIT READY command to the unit defined 


Syntax 

cgen_ready {pdrv_dev, action, done , sleep) 
PDRV_DEVICE *pdrv_dev; 
CGEN_ACI10N * action ; 
void ( *done) (); 
u_long sleep ; 


Arguments 

pdrv dev Pointer to the CAM Peripheral Device Structure allocated for each SCSI 
device in the system. 

action Pointer to the caller’s Generic Action Structure. 

done The address of the completion routine to be called when the SCSI 
command completes. 

sleep Whether or not the GENERIC_SLEEP flag is set. 

Description 

The cgen_ready routine issues a TEST UNIT READY command to the unit 
defined. The routine calls the ccmn_tur routine to issue the TEST UNIT READY 
command and sleeps waiting for command status. 

Return Value 

None 


See Also 

ccmn tur 
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Name 


cgen_slave - called at system boot to initialize the lower levels 


Syntax 

cgen_slave(wz, reg) 
struct uba_device *ui; 
caddr_t reg\ 


Arguments 

ui Pointer to the device information contained in the uba_device 

structure. 

reg The virtual address of the controller. 


Description 

The cgen_slave routine is called at system boot to initialize the lower levels. 
The routine also checks the bounds for the unit number to ensure it is within the 
allowed range and sets the device-configured bit for the device at the specified bus, 
target, and LUN. 


Return Value 

PROBE_FAILURE 

PROBE_SUCCESS 


See Also 

ccmn_close_unit, ccmn_init, ccmn_open_unit 
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Name 


cgen_strategy - handles all I/O requests for user processes 


Syntax 

cgen_strategy(6p) 

struct buf *bp\ 


Arguments 

bp A buf structure pointer, which is used for request mapping. 


Description 

The cgen_strategy routine handles all I/O requests for user processes. It 
performs specific checks, depending on whether the request is synchronous or 
asynchronous and on the SCSI device type. The cgen_strategy routine calls 
the ccmn_io_ccb_bld routine to obtain an initialized SCSI I/O CCB and build 
either a read or a write command based on the information contained in the buf 
structure. The cgen_strategy routine then calls the ccmn_send_ccb to 
place the CCB on the active queue and send it to the XPT layer. 


Return Value 

[EINVAL] 

[EIO] 


See Also 

ccmn_io_ccb_bld , ccmn_send_ccb , cgen_iodone 
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Name 


cgen_write - handles synchronous write requests for user processes 


Syntax 

cgen_write(<fev, uio ) 
dev_t dev; 
struct uio *uio; 


Arguments 

dev The major/minor device number pair that identifies the bus number, 

target ID, and LUN associated with this SCSI device. 

uio Pointer to the device information contained in the uio I/O structure. 


Description 

The cgen_write routine handles synchronous write requests for user processes. 
The routine passes the user process requests to the cgen_strategy routine. The 
cgen_write routine calls the ccmn_get_bp routine to allocate a buf structure 
for the user process write request. When the I/O is complete, the cgen_write 
routine calls the ccmn_rel_bp routine to deallocate the buf structure. 


Return Value 

The cgen_write routine passes the return from the physio routine. 

See Also 

ccmn_get_bp , ccmn_rel_bp , cgen_strategy 
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Name 


sim_action - initiates an I/O request from a SCSI/CAM peripheral device driver 


Syntax 

sim_action {ccbjidr) 
CCB_HEADER * ccbjidr, 


Arguments 

ccb hdr Address of the header for the ccb. 


Description 

The sim_action routine initiates an I/O request from a SCSI/CAM peripheral 
device driver. The routine is used by the XPT for immediate as well as for queued 
operations. When the operation completes, the SIM calls back directly to the 
peripheral driver using the CCB callback address, if callbacks are enabled and the 
operation is not to be carried out immediately. 

The SIM determines whether an operation is to be carried out immediately or to be 
queued according to the function code of the CCB structure. All queued operations, 
such as “Execute SCSI I/O” (reads or writes), are placed by the SIM on a nexus- 
specific queue and return with a CAM status of CAM_INPROG. 

Some immediate operations, as described in the American National Standard for 
Information Systems, SCSI-2 Common Access Method: Transport and SCSI Interface 
Module, working draft, X3T9.2/90-186, may not be executed immediately. However, 
all CCBs to be carried out immediately return to the XPT layer immediately. For 
example, the ABORT CCB command does not always complete synchronously with 
its call; however, the CCB_ABORT is returned to the XPT immediately. An 
XPTJRESET_BUS CCB returns to the XPT following the reset of the bus. 

Return Value 

CAM_REQ_INPROG for queued commands 
CAMJREQ_CMP for immediate commands 
A valid CAM error value 

See Also 

American National Standard for Information Systems, SCSI-2 Common Access 
Method: Transport and SCSI Interface Module, working draft, X3T9.2/90-186 
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Name 


sim_init - initializes the SIM 

Syntax 

simjnit (pathid) 
ujong pathid; 


Arguments 

pathid SCSI target’s bus controller number. 

Description 

The sim_init routine initializes the SIM. The SIM clears all its queues and 
releases all allocated resources in response to this call. This routine is called using 
the function address contained in the CAM_SIM_ENTRY structure. This routine can 
be called at any time; the SIM layer must ensure that data integrity is maintained. 

Return Value 

CAM_REQ_CMP 
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Name 


uagt_close - handles the close of the User Agent driver 

Syntax 

uagt_close(<fev, flag) 
dev_t dev; 
int flag ; 


Arguments 

dev The major/minor device number pair that identifies the User Agent. 
flag Unused. 

Description 

The uagt_close routine handles the close of the User Agent driver. For the last 
close operation for the driver, if any queues are frozen, a RELEASE SIM QUEUE 
CCB is sent to the XPT layer for each frozen queue detected by the User Agent. 

Return Value 

None 

See Also 

uagt_open, xpt_ccb_free 
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Name 


uagt_ioctl - handles the ioctl system call for the User Agent driver 

Syntax 

uagt_ioctl(dev, cmd, data, flag) 
dev_t dev, 
register int cmd; 
caddr_t data; 
int flag; 


Arguments 

dev The major/minor device number pair that identifies the User Agent. 
cmd The ioctl command, UAGT_CAM_IO. 

data Pointer to the UAGT_CAM_CCB structure passed by the user process. 
flag Unused. 

Description 

The uagt_ioctl routine handles the ioctl system call for the User Agent 
driver. The ioctl commands supported are: DEVIOCGET, to obtain the User 
Agent driver’s SCSI device status; UAGT_CAM_IO, the ioctl define for calls to 
the User Agent driver; UAGT_CAM_SINGLE_SCAN, to scan a bus, target, and 
LUN; and UAGT_CAM_FULL_SCAN, to scan a bus. 

For SCSI I/O CCB requests, the user data area is locked before passing the CCB to 
the XPT. The User Agent sleeps waiting for the I/O to complete and issues a 
ABORT CCB if a signal is caught while sleeping. 

Return Value 

The uagt ioctl routine returns a value of 0 (zero) upon successful completion. 

Diagnostics 

The uagt_ioctl routine fails under the following conditions: 

[EFAULT] Copy to or from user space failed. 

[EINVAL] An unsupported cmd value was passed to ioctl(). The CCB copied 
from the user process contained an invalid XPT function code, or 
an invalid target or LUN. 

[EBUSY] The maximum allowable number of User Agent requests has been 

reached (MAX_UAGT_REQ). 
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See Also 

ioctl(2), xpt_action, xpt_ccb_alloc 
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Name 


uagt_open - handles the open of the User Agent driver 

Syntax 

uagt_open (dev, flag) 
dev_t dev, 
int flag-. 


Arguments 

dev The major/minor device number pair that identifies the User Agent. 
flag Unused. 

Description 

The uagt_open routine handles the open of the User Agent driver. 

The character device special file name used for the open is /dev/c am. 

Return Value 

The uagt_open routine returns a value of 0 (zero) upon successful completion. 

See Also 

uagt_close, xpt_init 
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Name 


xpt_action - calls the appropriate XPT/SIM routine 


Syntax 

long xpt_action (ch) 
CCB_HEADER * ch; 


Arguments 

ch Specifies a pointer to the CAM Control Block (CCB) on which to act. 


Description 

The xpt_action routine calls the appropriate XPT/SIM routine. The routine 
routes the specified CCB to the appropriate SIM module or to the Configuration 
driver, depending on the CCB type and on the path ED specified in the CCB. 
Vendor-unique CCBs are also supported. Those CCBs are passed to the appropriate 
SIM module according to the path ID specified in the CCB. 


Return Value 

Upon completion, the xpt_action routine returns a valid CAM status value. 


See Also 

xpt_ccb_alloc, xpt_ccb_free 
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Name 


xpt_ccb_alloc - allocates a CAM Control Block (CCB) 


Syntax 

CCB_HEADER *xpt_ccb_alloc () 

Arguments 

None 


Description 

The xpt_ccb_alloc routine allocates a CAM Control Block (CCB) for use by a 
SCSI/CAM peripheral device driver. The xpt_ccb_alloc routine returns a 
pointer to a preallocated data buffer large enough to contain any CCB structure. The 
peripheral device driver uses this structure for its XPT/SIM requests. The routine also 
ensures that the SIM private data space and peripheral device driver pointer, 
cam_pdrv_ptr , are set up. 

Return Value 

Upon successful completion, xpt_ccb_alloc returns a pointer to a preallocated 
data buffer. The data buffer returned by xpt_ccb_alloc is initialized to be a 
SCSI I/O CCB. For other types of CCBs, some fields may have to be reinitialized 
for the specific CCB. 


See Also 

xpt_ccb_free 
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Name 


xpt_ccb_free - frees a previously allocated CCB 


Syntax 

long xpt_ccb_free(c/0 

CCB_HEADER *ch\ 


Arguments 

ch Specifies a pointer to the CCB to be freed. This CCB was allocated in a call 
to xpt_ccb_alloc. 


Description 

The xpt_ccb_free routine frees a previously allocated CCB. The routine returns 
a CCB, previously allocated by a peripheral device driver, to the CCB pool. 


Return Value 

XPT_CCB.INVALID or CAM.SUCCESS 

See Also 

xpt_ccb_alloc 
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Name 


xpt_init - validates the initialized state of the CAM subsystem 

Syntax 

long xptJnitQ 


Arguments 


None 


Description 


The xpt_init routine validates the initialized state of the CAM subsystem. The 
routine initializes all global and internal variables used by the CAM subsystem 
through a call to the Configuration driver. Peripheral device drivers must call this 
routine either during or prior to their own initialization. The xpt_init routine 
simply returns to the calling SCSI/CAM peripheral device driver if the CAM 
subsystem was previously initialized. 

Return Value 


Upon completion, 

xpt_init returns one of the following values: 

Return Value 

Meaning 

CAM_SUCCESS 

The xpt init routine initialized the CAM 
subsystem. 

CAM_FAILURE 

The xpt_init routine did not initialize the CAM 
subsystem and the CAM subsystem cannot be used. 
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Index 


A 

ABORT CCB (CAM), 5-6 

B 

BUS DEVICE RESET CCB (CAM), 5-6 
BUS RESET CCB (CAM), 5-6 

c 

CALLD macro (CAM), 10-1 
CAM 

common structures and routines, 1-4 
Configuration driver structures and routines, 1-5 
generic structures and routines, 1-5 
overview, 1-1 

SCSI CDROM/AUDIO device structures and 
commands, 1-5 

SCSI disk device structures and routines, 1-5 
SCSI tape device structures and routines, 1-5 
SCSI/CAM peripheral drivers, 1-4 
SCSI/CAM special I/O interface, 1-5 
SIM SCSI Interface layer, 1-6 
User Agent driver structures and routines, 1-3 
XPT transport layer, 1-6 
CAM common close unit routine 
See also CAM open unit routine 
CAM common data structures 
introduction, 3-1 
CAM common macros 
introduction, 3-5 
CAM common routines 
introduction, 31-1, 3-6 
CAM Control Block (CAM), 5-1 


CAM Control Block (CCB) header structure 
(CAM), 5-2 
CAM Control Blocks 
described, 5—It 
CAM debug macros 
described, 10-1 
introduction, 10-1 
CAM debug routines 
introduction, 10-1 

CAM equipment device table (CAM), 6-2 
CAM error handling 

CAM_ERROR macro, 9-1 
introduction, 9-1 

CAM error-logging data structures 
introduction, 9-2 

CAM generic maximum transfer limit routine, 4-8, 
C-79 

CAM identification macros 
described, 3—5t 
CAM locking macros 
described, 3-5t 

CAM programmer-defined routines 
introduction, 11-1 

CAM programmer-defined structures 

introduction, 11-1 
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TERMINATE I/O CCB, 5-6 
UAGT_CAM_CCB, 2-2 
UAGT_CAM_SCAN, 2-4 
CAM User Agent driver 
error handling, 2-1 
introduction, 2-1 
CAM XPT routines 
introduction, 7-1 
CAMJERROR macro (CAM) 
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cdbg_CamFunction (CAM), 10-4, C-57 
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cdbg_DumpBuffer (CAM), 10-6, C-60 
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cdbgJDumpInquiryData (CAM), 10-6, C-64 
cdbg_DumpPDRVws (CAM), 10-6, C-65 
cdbg_DumpSCSnO (CAM), 10-6, C-66 
cdbg_DumpTERMIO (CAM), 10-6, C-67 
cdbg_GetDeviceName (CAM), 10-6, C-68 
cdbg_ScsiStatus (CAM), 10-5, C-69 
cdbg_SystemStatus (CAM), 10-5, C-70 
CDB_UN structure (CAM), 5-5 
CGEN_ACTION (CAM), 4-3 
cgen_async (CAM), 4-7, C-71 
cgen_attach (CAM), 4-8, C-72 


cgen_ccb_chkcond (CAM), 4-7, C-73 
cgen_close (CAM), 4-5, C-75 
cgen_done (CAM), 4-7, C-76 
cgen_ioctl (CAM), 4-6, C-77 
cgenjiodone (CAM), 4-7, C-78 
cgen_minphys (CAM), 4-8, C-79 
cgen_mode_sns (CAM), 4-9, C-80 
cgen_open (CAM), 4-5, C-81 
cgen_open_jsel (CAM), 4-9, C-83 
cgen_read (CAM), 4-5, C-84 
cgenjready (CAM), 4-8, C-85 
cgen_slave (CAM), 4-8, C-86 
CGEN_SPECIFIC (CAM), 4-2 
cgen_strategy (CAM), 4-6, C-87 
cgen_write (CAM), 4-6, C-88 
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C-9, C-10 

common bus-device-reset CCB routine (CAM), 
3-12, C-12 

common bus-reset CCB routine (CAM), 3-12, C-14 
common close unit routine (CAM), 3-8, C-18 
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ccmn_mode_select command (CAM), 3-13, 
C-31 
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command (CAM), 3-13, C-49 
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READY command (CAM), 3-13, C-55 
common create SCSI VO CCB routine (CAM), 

3-11, C-29 
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introduction, 3-1 

common deallocate buf structure routine (CAM), 
3-14, C-37 

common deallocate data buffer routine (CAM), 
3-14, C-39 

common error logging routine (CAM), 3-15, C-19 
common get buf structure routine (CAM), 3-14, 
C-22 

common get CCB routine (CAM), 3-10, C-24 
common get data buffer routine (CAM), 3-14, C-25 
common get-device-type CCB routine (CAM), 3-11, 
C-21 


Index-4 



common initialization routine (CAM), 3-8, C-26 
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common open unit routine (CAM), 3-8, C-33 
See also common close unit routine (CAM) 
common path-inquiry CCB routine (CAM), 3-11, 
C-36 
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common release-SIM-queue CCB routine (CAM), 
3-11, C-42 

common remove CCB routine (CAM), 3-9, C-40 
common routine to assign generic status categories 
(CAM), 3-13, C-15 
common routines (CAM) 
introduction, 3-1 

common send CCB routine (CAM), 3-9, C—47 
common set-asynchronous-callback CCB routine 
(CAM), 3-11,0-44 

common set-device-type CCB routine (CAM), 3-11, 
C-46 

common special command interface routine 
(CAM), 3-15, C-6, C-7 

common terminate CCB routine (CAM), 3-9, C-53 
common terminate I/O CCB routine (CAM), 3-12, 
C-52 

Configuration driver (CAM) 
and XPT routines, 6-1 

Configuration driver configuraton file (CAM), 6-3 
sample entry, 6-4 

Configuration driver control structure (CAM), 6-2 
Configuration driver data structures (CAM) 
CAM_PERIPHERAL_DRIVER, 6-3 
CCFG.CTRL, 6-2 
EDT, 6-2 
introduction, 6-1 
Configuration driver routines 

entry-point routine introduction, 6-4 
Configuration driver routines (CAM) 
ccfg_action, 6-5 
ccfg_attach, C-3, 6-5 
ccfg_edtscan, C-4, 6-5 
ccfg_slave, C-5, 6-5 
description, 6-1 
introduction, 6-1 
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introduction, 10-1 
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sample entry, 11-9 

DENSITY.TBL structure (CAM), 3-4, 11-8 
DEVJDESC structure (CAM), 11-5 
Device Descriptor Structure structure (CAM), 11-5 
device driver 

summary of device driver routines, B-lt 
DISKjSPECIFIC structure (CAM), 11-14 
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Error Entry Structure (CAM), 9-2 
error handling (CAM) 

CAM_ERROR macro, 9-1 
introduction, 9-1 

Error Header Structure (CAM), 9-3 
error-logging data structures (CAM) 
CAM_ERR_ENTRY, 9-2 
CAM_ERR_HDR, 9-3 
introduction, 9-2 
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generic action data structure (CAM), 4-3 
generic asynchronous event handling routine 
(CAM), 4-7, C-71 

generic attach routine (CAM), 4-8, C-72 
generic close unit routine (CAM), 4-5, C-75 
See also generic open unit routine (CAM) 
generic completion routine (CAM), 4-7, C-76 
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introduction, 4-2 
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generic open unit routine (CAM), 4-5, C-81 
See also generic close unit routine (CAM) 
generic read routine (CAM), 4-5, C-84 
See also generic write routine (CAM) 
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generic routines (CAM) 
error handling, 4-2 
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introduction, 4-1 
kernel entry points, 4-2 
rules, 4-1 

generic slave routine (CAM), 4-8, C-86 
generic strategy routine (CAM), 4-6, C-87 
generic write routine (CAM), 4-6, C-88 
See also generic read routine (CAM) 
generic-specific data structure (CAM), 4-2 
GET DEVICE TYPE CCB (CAM), 5-7 
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header files 

header files Used by device drivers, A-lt 
header files Used by SCSI/CAM device drivers, 
A-3t 

M 

Mode Select Table Structure (CAM), 3-3, 11-9 
Mode Select Table Structure structure (CAM) 
sample entry, 11-11 

MODESEL_TBL structure (CAM), 3-3, 11-9 
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PATH INQUIRY CCB (CAM), 5-7 
PDRVJDEVICE structure (CAM), 3-2, 11-2 
PDRV_WS structure (CAM), 3-4 
Peripheral Device Unit Table structure (CAM), 
3-1, 11-1,11-2 
PRINTD macro (CAM), 10-1 
programmer-defined routines (CAM) 
introduction, 11-1 

programmer-defined structures (CAM) 
introduction, 11-1 
samples, 11-11 
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RELEASE SIM QUEUE CCB (CAM), 5-5 
routine to dump a CCB_ABORT (CAM), 10-6, 
C-59 

routine to dump a CCBJHEADER (CAM), 10-5, 
C-61 

routine to dump a CCB_SCSIIO (CAM), 10-6, 
C-66 

routine to dump a CCB_TERMIO (CAM), 10-6, 
C-67 

routine to dump a data buffer (CAM), 10-6, C-60 
routine to dump a PDRV.WS (CAM), 10-6, C-65 
routine to dump an ALLJNQJDATA structure 
(CAM), 10-6, C-64 

routine to dump cam_flags from a CCBJHEADER 
(CAM), 10-5, C-63 

routine to dump the device type (CAM), 10-6, 

C-68 

routine to fill in an error log packet (CAM), C-2, 
9-4 

routine to print CAM status codes (CAM), 10-4, 
C-58 

routine to print SCSI status codes (CAM), 10-5, 
C-69 

routine to print system error codes (CAM), 10-5, 
C-70 

routine to print XPT function codes (CAM), 10-4, 
C-57 
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SCSI CDROM/AUDIO device cd_address structure 
(CAM), 11-17 

SCSI CDROM/AUDIO device 

CDROMJPLAY_AUDIO and 
CDROM_PLAY_VAUDIO commands 
structure (CAM), 11-18 
SCSI CDROM/AUDIO device 

CDROM_PLAY_AUDIO_MSF and 
CDROM_PLAY_MSF commands structure 
(CAM), 11-18 

SCSI CDROM/AUDIO device 

CDROM_PLAY_AUDIO_TI command 
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structure (CAM) 

SCSI CDROM/AUDIO device 

CDROM_PLAY_AUDIO_TI command 
structure (CAM) (cont.) 

Book Title (cont.) 

11-19 (cont.) 

(cont.) 

(cont.) ,11-19 

SCSI CDROM/AUDIO device 

CDROM_PLAY_AUDIO_TR command 
structure (CAM), 11-20 
SCSI CDROM/AUDIO device 

CDROMJPLAYBACK_CONTROL and 
CDROM_PLAYBACK_STATUS commands 
structures (CAM), 11-27 
SCSI CDROM/AUDIO device 

CDROMJPLAYBACK_CONTROL 
command structure (CAM), 11-28 
SCSI CDROM/AUDIO device 

CDROMJPLAYBACK_STATUS command 
structure (CAM), 11-28 
SCSI CDROM/AUDIO device 

CDROMJPLAYJTRACK command 
structure (CAM), 11-27 
SCSI CDROM/AUDIO device 

CDROM_READ_HEADER command 
structures (CAM), 11-26 
SCSI CDROM/AUDIO device 

CDROMJREAD_SUBCHANNEL command 
structure (CAM), 11-22 
SCSI CDROM/AUDIO device 

CDROM_TOC_ENTRYS command 
structures (CAM), 11-21 
SCSI CDROM/AUDIO device 

CDROM_TOC_HEADER command 
structure (CAM), 11-20 
SCSI CDROM/AUDIO device Track Address 
structure (CAM), 11-17 
SCSI device 

attaching, 4-8, C-72 

closing, 2-4, 3-8,4-5, C-18, C-75, C-91 
opening, 2-4, 3-8,4-5, C-33, C-81, C-94 
reading, 4-5, C-84 
writing, 4-6, C-88 
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(CAM) 

adding entries, 6-3 
sample entry, 6-4 

SCSI/CAM Special Command Table (CAM), 12-3 
entries, 12-5 

SCSI/CAM Special Command Table (CAM) 
example, 12-7 

SCSI/CAM special I/O interface (CAM), 12-1 
See also generic routines (CAM) 
application program access, 12-1 
co mm and table entries, 12-5 
command table example, 12-7 
command tables, 12-3 
control command, 12-16, 12-17 
device driver access, 12-2 
introduction, 12-1 

I/O control command processing, 12-8 
sample code, 12-20, 12-22 
sample function, 12-14, 12-15, 12-19 
SCSI/CAM Special Command Table, 12-3 
SCSI/CAM Special Command Table entries, 12-5 
SCSI/CAM Special Command Table example, 
12-7 

Special I/O Control Commands Structure, 12-16, 
12-17 

SPECIALHEADER, 12-3 
SET ASYNCHRONOUS CALLBACK CCB 
(CAM), 5-5 

SET DEVICE TYPE CCB (CAM), 5-7 
SIM action routine (CAM), 8-2, C-89 
SIM initialization routine (CAM), 8-2, C-90 
SIM routines (CAM) 
introduction, 8-1 
sim_action (CAM), 8-2, C-89 
simjnit (CAM), 8-2, C-90 
Special I/O Argument Structure (CAM), 12-8 
Special I/O Control Commands Structure (CAM), 
12-16,12-17 

SPECIAL_HEADER (CAM), 12-3 
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TAPE_SPECIFIC structure (CAM), 11-11 
TERMINATE I/O CCB (CAM), 5-6 
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UAGT_CAM_CCB (CAM), 2-2 
UAGT_CAM_SCAN (CAM), 2-4 
uagt_close (CAM), 2-4, C-91 
uagtjoctl (CAM), 2-5, C-92 
uagt_open routine (CAM), 2-4, C-94 
USCA (CAM) 

common structures and routines, 1-4 
Configuration driver structures and routines, 1-5 
generic structures and routines, 1-5 
overview, 1-1 

SCSI CDROM/AUDIO device structures and 
commands, 1-5 

SCSI disk device structures and routines, 1-5 
SCSI tape device structures and routines, 1-5 
SCSI/CAM peripheral drivers, 1-4 
SCSI/CAM special I/O interface, 1-5 
SIM SCSI Interface layer, 1-6 
User Agent driver structures and routines, 1-3 
XPT transport layer, 1-6 
User Agent close routine 

See also User Agent open routine 
User Agent close routine (CAM), 2-4, C-91 
User Agent driver (CAM) 
error handling, 2-1 
introduction, 2-1 
sample inquiry programs, 2-5 
sample programs, 2-5 
sample scanner programs, 2-15 
User Agent ioctl routine (CAM), 2-5, C-92 
User Agent open routine 

See also User Agent close routine 
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XPT free CCB routine (CAM), C-97, 7-1 
XPT initialization routine (CAM), C-98, 7-2 
XPT routines 

xpt_ccb_alloc, C-96, 7-1 


XPT routines (CAM) 
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XPT routing routine (CAM), C-95, 7-1 
xpt_action (CAM), C-95,7-1 
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xpt_ccb_free (CAM), C-97, 7-1 
xptjnit (CAM), C-98, 7-2 
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